API design overview

This page applies to Apigee and Apigee 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:

• An OpenAPI document
• A GraphQL 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 this blog 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, see https://openapis.org.

An OpenAPI 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 on GitHub.

Tip: Apigee supports OpenAPI Specification 3.0, though a subset of features are not yet supported. See Apigee known issues and select Integrated portal in the Filter by RELEASE drop-down.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Many excellent sources of information about OpenAPI Specifications exist. A good place to start is the OpenAPI Initiative site, where you'll find overviews, blogs, and links to the OpenAPI 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 the OpenAPI Specification repository.

Note: To try out a working example, see Creating an API proxy from an OpenAPI Specification.

What is a GraphQL schema?

A GraphQL 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, see graphql.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.

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  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 the API 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 the API 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 in Using OpenAPI Specifications to generate proxies. For a hands-on experience, step through the Creating an API proxy from an OpenAPI Specification tutorial.

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