An API description language (or API description format) is a standard format for describing APIs. For example, the snippet below informs the consumers of our API that they need to provide a JSON payload with an email and digest field when calling the POST /login endpoint. In return, they can expect our API to respond with one of the four listed status codes:

paths:
  /login:
    post:
      requestBody:
        description: User Credentials
        required: true
        content:
          application/json:
            schema:
              properties:
                email:
                  type: string
                  format: email
                digest:
                  type: string
                  pattern: ^\\$2[aby]?\\$\\d{1,2}\\$[.\\/A-Za-z0-9]{53}$
      responses:
        '200':
          $ref: '#/components/responses/LoginSuccess'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'

There are several benefits to writing an API specification:

• The specification acts as a contract between our platform and the end consumers, which may not be limited to just developers, but also other internal APIs as well. Having a contract means consumers of our API are able to develop their integrations before our API is complete—because we have agreed, through the specification, how our API should behave—as long as everyone stays faithful to the API specification, the integration will be successful.
• It forces us to design the interface.
• We can create mock servers. These mock servers mimic the behavior of the real API server, but responds with canned responses instead. We can provide this mock server for end consumers before our API is complete, so they'll know how our API should respond.
• Using open source tools (such as Dredd—dredd.org), we can automatically test our API server to see if it complies with the specification.
• Using tools that integrate with our API server, we can use the specification to validate requests and responses automatically, without having to write extra validation code.