Research - Describing an API Design

[jamescd18]

As part of our application infrastructure moving data from the database to the API and finally to the front-end, we need a way to describe and model our API. Where ERDs and Relational Schemas define databases, RAML and OAS are the two most popular formats for describing APIs. Research those two formats.

[jamescd18]

Let's use OAS (OpenAPI). Place it in a .yaml file in the backend probably.

[jamescd18]

Interesting backend exploration example:

URL: http://localhost:3000/.netlify/functions/example/12412/edit:cancel?q=sdklfjsldfjk&h=353&wbs=1.1.1

Output:

[jamescd18]

Some links:

• https://swagger.io/docs/specification/basic-structure/
• https://editor.swagger.io
• https://swagger.io/docs/specification/components/
• https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html

[jamescd18]

Looks like Netlify functions upgraded to the latest version of AWS Lambda, so now we get more parameters in the Event and Context objects.

[jamescd18]

At this point in the project, formalized API documentation would be a burden on the team for very little value. The API design is rapidly changing and there are no planned external users of the API, so I don't believe we would get any benefits from formalized API documentation. In the future, once an MVP is created, a clean set of API documentation would be valuable to have.