API 관련 용어 집중 과정

Specification is some standard or RFC or whatever describing a particular format or protocol.

Schema (aka: data model) is a metadata describing the data type, formats, and validation rules. Schema can be defined for content body, header, path or query parameters, etc.

Hypermedia controls is an easier way to say HATEOAS. What’s that? It’s a special affordance that allows a client to traverse API without hardcoding links. The simplest example would be including pagination links in the response data. E.g., a client asked to get collection of items — the server responded with first N items and a link to the next page of results — the client can use the link to get the next page without constructing a link on their own.

{
    "items": [
        {"id": 1},
        {"id": 2}
    ],
    "links": {
        "next": { "href": "/api/items?cursor=ae12fb2" }
    }
}

Description (aka: definition, contract) is a metadata about API, its endpoints, resources, operations, headers, parameters, and etc.

API description document is a file that contains API description. It is usually written with a particular format from specifications like OpenAPI, WSDL, RAML.

API documentation is a collection of information pieces that allows clients to successfully use an API. It includes, but not limited to, an API reference documentation (which is often generated from description document). Other important pieces are: tutorials, concept explanations, registration helpers, SDKs.

There are tons of API-related specifications. I’ll cover only some.

API description doc is often written in machine-readable format, thus, we can manipulate it and check for errors.

Validation checks that description doc conforms to some specification.

Linting checks custom rules like style. For example: check that all paths are lowercase.

Preprocessing allows transforming the doc based on additional rules before using it in code or documentation generation. For example, hiding some endpoints from the published version or injecting descriptions from markdown files.

When working with OpenAPI or JSON Schema you will stumble upon $ref ’s a great deal. These are pointers to JSON structures in different locations: inside the same file or to some other file:

For example, this reference points to the schema from the other file.

...
application/json:
  schema:
    type: object
    properties:
      data:
        $ref: ../components/schemas/Users/User.yaml

References help with structuring schemas, separating them into reusable pieces.

The process of looking for value of $ref is called resolution (or lookup). Not all tools and libraries play well with multi-file resolutions, so you may want to do one of these:

• Bundling (aka: external inlining) replaces $ref ’s to external files with internal references. This creates one file that is easier to share.
• Dereferencing (aka: internal inlining) replaces $ref ’s to external or internal data with actual data. The resulting file will have no $ref ’s, but will be noticeably bigger.