This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

In the Design phase, you define the requirements for your API. As an API designer, you plan the services you'd like to expose to consumers, and design APIs to access those services. You create one of the following documents to capture your API requirements:

• AnOpenAPI document
• AGraphQL schema

The following sections provide more information about OpenAPI and GraphQL documents and the role they play in the lifecycle of your API. For a comparison of the two API design options, see REST and GraphQL compared in thisblog post.

What is the OpenAPI Specification?

"The OpenAPI Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API Description Format based on the Swagger Specification." For more information about the OpenAPI Initiative, seehttps://openapis.org.

AnOpenAPI document uses a standard format to describe a RESTful API. Written in either JSON or YAML format, an OpenAPI document is machine readable, yet also easy for humans to read and understand. The OpenAPI Specification enables formal description of elements of an API such as its base path, paths and verbs, headers, query parameters, content types, response models, and more. In addition, an OpenAPI document is commonly used to generate API documentation.

Here's a fragment from an OpenAPI document that describes Apigee's simple hello world sample. For more information, view the OpenAPI Specification onGitHub.

openapi:3.0.0info:description:OpenAPISpecificationfortheApigeemocktargetserviceendpoint.version:1.0.0title:MockTargetAPIpaths:/:get:summary:ViewpersonalizedgreetingoperationId:Viewapersonalizedgreetingdescription:Viewapersonalizedgreetingforthespecifiedorguestuser.parameters:-name:userin:querydescription:Yourusername.required:falseschema:type:stringresponses:"200":description:Success/help:get:summary:GethelpoperationId:Gethelpdescription:ViewhelpinformationaboutavailableresourcesinHTMLformat.responses:"200":description:Success...

Many excellent sources of information about OpenAPI Specifications exist. A good place to start is theOpenAPI Initiative site, where you'll find overviews, blogs, and links to theOpenAPI Specification. Refer to the Specification for detailed descriptions of the schema elements and data types.

There are a number of JSON and YAML example OpenAPI documents that you can download from theOpenAPI Specification repository.

What is a GraphQL schema?

AGraphQL schema describes the data available in your API for a client to query.

Benefits of using GraphQL include:

• A single endpoint provides access to all fields for a given operation
• The powerful query language, called Schema Definition Language, enables you to access exactly the data you need, preventing over-fetching or under-fetching of data
• Processing of queries happens in parallel

For more information about GraphQL, seegraphql.org.

The following provides an example of a GraphQL schema that defines the data entry point (Query type), available write operations (Mutation type), and data types.

typeQuery{Greeting:Stringstudents:[Student]}typeMutation{createStudent(firstName:String!,lastName:String!):Student!}typeSubscription{newStudent:Student!}typeStudent{Id:ID!firstName:String!lastName:String!password:String!collegeId:String!}

You can query the GraphQL schema to return the exact data you need as a JSON payload.

What happens if I modify a document?

Each OpenAPI or GraphQL document serves as the source of truth throughout the API lifecycle. The same document is used at each phase in the API lifecycle, from development to publishing to monitoring.

When you edit or delete a document, it has impact down the line:

• If you edit a document, you need to manually edit the related artifacts including the API proxy and any API products that expose its resources, and regenerate theAPI reference documentation to reflect the changes implemented in the document.
• If you delete a document, you need to manually delete the related artifacts including the API proxy and edit any API products to delete related resources, and regenerate theAPI reference documentation to reflect the removal of the document and its resources.

What happens when I create an API proxy from an OpenAPI document?

You can create your API proxies from your OpenAPI documents. In just a few clicks, you'll have an API proxy with the paths, parameters, conditional flows, and target endpoints generated automatically. Then, you can add features such as OAuth security, rate limiting, and caching.

You can create an API proxy from an OpenAPI document using the Create Proxy Wizard, as described inUsing OpenAPI Specifications to generate proxies. For a hands-on experience, step through theCreating an API proxy from an OpenAPI Specification tutorial.

When youpublish your API, you take asnapshot of the OpenAPI document to generate API reference documentation. That snapshot represents a specific revision of the description document.