OpenAPI: How to Design API Specifications

OpenAPI Building Blocks

  • Metadata: This section encodes information about the API specification itself, like version, title, author or further links
  • Servers: A list of servers that offer the API you are describing, it is used by some tools to generate curl statements that you can use live to query the API
  • Endpoints: The concrete endpoints of your API, described as complex objects with this information: Path, HTTP methods, parameters (required/optional), and responses with status code, content-type and response
  • Schemas/Definitions: All structured data objects, either used in requests or returned in the response, can be defined in this section and then referenced from other parts within the specification

Example: Lighthouse API

OpenAPI Declaration for Lighthouse

Info and Listing Servers

openapi: 3.0.0
info:
version: 1.0
title: Lighthouse API
servers:
- url: https://lighthouse.admantium.com/
servers:
- url: https://lighthouse.admantium.com/

Scanner Endpoint

  • You define the endpoints in a section called paths
  • Each path has at least one HTTP method: get, post, put, option, query, delete
  • Each method has a description, parameters and responses
  • responses have at least one status code that they return.
paths:
/scan:
get:
description: Initiate a webpage scan
parameters:
...
responses:
200:
...
400:
...
429:
...
paths:
/scan:
get:
description: Initiate a webpage scan
parameters:
- name: url
in: query
schema:
type: string
paths:
/scan:
get:
# ...
responses:
200:
description: Webpage scan is accepted and will be processed
content:
application/json:
schema:
$ref: '#/components/schemas/ScanResponse'
400:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultError'
429:
description: Scan requests can not be accepted, all workers are occupied
content:
application/json:
schema:
$ref: '#/components/schemas/ScanResponse'

Job Endpoint

/api/jobs:
get:
description: Get the job status for the provided `uuid`
parameters:
- name: uuid
in: query
schema:
type: string
responses:
responses:
200:
description: 'JOB status: finished'
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
202:
description: 'JOB status: started'
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
400:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultError'
409:
description: 'JOB status: error'
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'

Defining Request or Response JSON Payload Data Structures

responses:
200:
description: Webpage scan is accepted and will be processed
content:
application/json:
schema:
$ref: '#/components/schemas/ScanResponse'
components:
schemas:
ScanResponse:
type: object
properties:
msg:
type: string
code:
type: integer
uuid:
type: string
JobResponse:
type: object
properties:
msg:
type: string
code:
type: integer
job:
type: object
properties:
uuid:
type: string
domain:
type: string
status:
type: string
record:
type: boolean

Complete Example

Summary

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store