Overview of API design

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 RESTful APIs to access those services. You create an OpenAPI Specification in an easy-to-read JSON or YAML format to capture your API requirements.

The following sections provide more information about OpenAPI Specifications and the role they play in the lifecycle of your API.

What is an OpenAPI specification?

An OpenAPI Specification uses a standard format to describe a RESTful API. Written in either JSON or YAML format, an OpenAPI Specification is machine readable, but is also easy for humans to read and understand. The specification describes 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 Specification is commonly used to generate API documentation.

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

swagger: '2.0'
info:
  description: 'OpenAPI Specification for the Apigee mock target service endpoint.'
  version: 1.0.0
  title: Mock Target API
host: mocktarget.apigee.net
schemes:
  - http
  - https
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      produces:
        - text/plain
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          type: string
      responses:
        '200':
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      produces:
        - text/html
      responses:
        '200':
          description: Success
...

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

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

What happens if I modify a specification?

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

When you edit or delete an OpenAPI Specification, it has impact down the line:

  • If you edit a specification, 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 specification.
  • If you delete a specification, 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 specification and its resources.

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

In Edge, you can create your API proxies from your OpenAPI Specifications. 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 Specification, as described in the following sections:

When you publish your API, you take a snapshot of the OpenAPI Specification to generate API reference documentation. That snapshot represents a specific version of the specification in the spec store.