Exploring the API-First Design Pattern | by John Vester | Apr, 2022

From a profession perspective, the 2 issues I respect probably the most are fixing issues by means of expertise and creating technical publications. The previous usually drives the latter: outcomes offered in inspired-based publications are derived from a latest downside that I had efficiently solved.

Alongside my three-decade journey, I additionally found that I take pleasure in making lists. Early in my profession, I used quad-ruled notebooks to ascertain lists to work from day by day.

After all, these graphically-lined requirements have fallen apart in favor of utilizing derived lists maintained on Trello or JIRA boards. For smaller tasks, I are likely to lean towards utilizing the Sublime and Atom textual content editors. What has not modified is my most well-liked method to work from a listing.

For bigger initiatives, merely working from a listing doesn’t present sufficient particulars. That is usually the case with concepts I’ve for a brand new publication.

In these circumstances, I introduce sub-items to every core checklist merchandise. Whereas it’s attainable to incorporate little one gadgets on the sub-item degree, I usually discover that I get into the weeds and never specializing in the broader panorama.

As soon as there’s good protection for every merchandise on the checklist, I determine how finest to order every merchandise. Throughout this step, the checklist really turns into an overview, the place there’s a sequence established to my assortment of ideas or concepts.

The ensuing product is what I’ve ended up utilizing for each publication I’ve submitted since 2015. Nonetheless, the define idea has not been restricted to my technical writing. I’ve additionally employed this exact same method when constructing APIs.

Janet Wagner famous that an API-first method “treats APIs with significance, as reusable and simply accessible merchandise that consumer purposes eat. API-first means designing merchandise round an API from the bottom up, somewhat than constructing a product and including an API later.”

After establishing API requirements, the API-first design sample allocates time at first of the method to provide a strong API design, specializing in high-level traits, which embody:

  • Useful resource path (URI)
  • Operation/Request varieties (GET, PUT, POST, PATCH, DELETE)
  • Inbound parameters/payload
  • Outbound response codes (1xx, 2xx, 3xx, 4xx, 5xx)
  • Outbound response payload (kind and information mannequin)
  • Further meta-data (description, contact, phrases of use)

When creating these specs I like to recommend the next lifecycle:

Within the illustration above, step one is to hear to the wants of the API and to repeat any necessities again to the product proprietor driving the underlying enterprise guidelines. After reaching that understanding, the design part begins by leveraging a standards-based specification (like OpenAPI). Lastly, shoppers of the API can preview it.

Typically, the cycle doesn’t finish there, as questions and challenges come up from the preview part. At that time, it’ll require further time to share these considerations with the product proprietor, who will present further data. At that time, the cycle begins with the aim of offering a more-refined API specification.

By using an API-first design sample, a single-source-of-truth artifact is documented earlier than writing a single line of code. The specification for the API will stay outdoors the supply methods that produce the precise API in a fashion that may be simply cataloged and consumed by future consumer and repair engineers.

Now, let’s get began and work by means of a easy use case.

After lately shifting into our new residence, I considered a use case as an example the API-first design sample. My thought facilities round cardboard bins used for shifting one’s possessions.

Packing containers are needed earlier than you begin packing to maneuver into a brand new residence. In case you’re like me, discovering bins which can be nonetheless in good condition and for little or no price is a perfect scenario. Then, after the transfer is full, discovering somebody to take your gently-used bins is simply as vital to keep away from a not-so-attractive cardboard show within the nook of your storage.

Enter the Field Finders API, the place clients carry out the next operations:

  • GET /bins — returns a listing of obtainable field collections
  • GET /bins/id — retrieves a single field assortment
  • POST /bins — provides a brand new field assortment
  • PUT /bins/id — updates an current field assortment
  • DELETE /bins/id — removes an current field assortment

For simplicity, let’s assume the Field Finders API requires the next attributes:

  • Id — distinctive numeric identifier for the field assortment
  • Identify — the title of the particular person to contact
  • Cellphone — the contact’s cellphone quantity
  • Obtainable — the variety of obtainable bins

Since I had not used the Kong Insomnia software earlier than, I believed I’d give it a attempt for proving out the API-first design sample.

As soon as installed, getting began with an API-first design begins with utilizing the Create menu on the left-side of Kong Insomnia:

Upon deciding on the Design Doc possibility, the subsequent step is to offer a reputation. For this instance, I entered box-finders-spec.yaml.

At this level, an empty design doc opens in Kong Insomnia:

Now, we’re prepared to start out designing the Field Finders API.

Including Common Data

On the high of the file, you possibly can add some normal details about the specification. I used OpenAPI model 3.0.0:

openapi: 3.0.0

information:
model: "0.0.1"
title: "Field Finders API"

Including Schema Data

Primarily based upon the present understanding of the Field Finders API, I added the information fashions (also called schema parts) to the underside of the file:

parts:
schemas:
Packing containers:
kind: array
gadgets:
$ref: "#/parts/schemas/Field"
Field:
kind: object
properties:
id:
kind: quantity
description: Distinctive identifier
title:
kind: string
description: Particular person with bins to offer away
cellphone:
kind: string
description: Cellphone variety of particular person with bins to offer away
obtainable:
kind: quantity
description: Variety of obtainable bins
Error:
kind: object
required:
- code
- message
properties:
code:
kind: integer
format: int32
message:
kind: string

Taking this method will hold the information aspect of the contract outlined in a single central location of the API specification.

Including /bins URIs

With the final data and schema sections in place, we are able to add the /bins URIs as path gadgets following the OpenAPI requirements:

paths:
/bins:
get:
abstract: "Lists all obtainable field collections"
responses:
"200":
description: "200 OK, all field collections"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Packing containers"
submit:
abstract: "Provides a brand new field assortment"
requestBody:
content material:
software/json:
schema:
$ref: "#/parts/schemas/Field"
required: true
responses:
"201":
description: "201 Created, a brand new field assortment was added"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Field"

On this instance, I’ve added URIs to retrieve all field collections and create a brand new field assortment beneath the paths part.

Including /bins/id URIs

Subsequent, I added the flexibility to retrieve, edit, or delete a single field assortment as further paths, nonetheless following the OpenAPI customary:

/bins/id:
parameters:
- in: path
title: id
schema:
kind: quantity
required: true
description: "id of the field assortment"
get:
abstract: "Retrieves a field assortment by identifier"
responses:
"200":
description: "200 OK, field assortment by identifier"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Field"
"404":
description: "404 Not Discovered, field assortment doesn't exist"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Error"
put:
abstract: "Updates a field assortment by identifier"
requestBody:
content material:
software/json:
schema:
$ref: "#/parts/schemas/Field"
responses:
"202":
description: "202 Accepted, up to date field assortment"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Field"
"404":
description: "404 Not Discovered, field assortment doesn't exist"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Error"
delete:
abstract: "Deletes a field assortment by identifier"
responses:
"204":
description: "204 No Content material, deleted field assortment"
"404":
description: "404 Not Discovered, field assortment doesn't exist"
content material:
software/json:
schema:
$ref: "#/parts/schemas/Error"

At this level, the 0.0.1 model of the Field Finders API is full. Nonetheless, earlier than shifting ahead, I felt prefer it was a very good time to retailer this data inside a git-based repository. This manner, the design just isn’t restricted to current on my native machine.

Connecting to GitHub

The Kong Insomnia consumer permits integration with an current git-based repository. I created a brand new repository on the following URL:

https://github.com/johnjvester/box-finders-api

Subsequent, I created a personal access token to create learn/write entry to the GitHub repository. Then, I used that ensuing token to arrange entry inside Kong Insomnia for the Field Finders API specification:

At this level, I dedicated my adjustments and pushed them to GitHub. As soon as accomplished, the adjustments from Kong Insomnia are actually obtainable for others to tug into their very own consumer:

Others who want to overview or contribute to the specification can use the Git Clone possibility from the Create menu.

Kong Insomnia Exhibiting Full API

With the adjustments famous above, Kong Insomnia exhibits the contents of the API:

At this level, the Field Finders API specification will be consumed by service and client builders with out writing a single line of code.

Utilizing Field Finders API

For circumstances the place a client of the Field Finders API needs to develop their software whereas the function workforce is creating the Field Finders RESTful service, Kong Insomnia offers the whole contract for the brand new consumer to make the most of:

When making a GET request to the /bins URI, the service will return a listing of Field objects:

[

"id": 0,
"name": "string",
"phone": "string",
"available": 0

]

Utilizing the API-first design sample, each consumer or service tied to the Field Finders API can start their improvement earlier than writing a single line of code for the Field Finders service.

Deploying to Kong Dev Portal

In case you’ve set up an account with Kong Konnect to make use of the Kong Dev Portal, you should utilize the Deploy to Dev Portal menu possibility on the Field Finders specification menu:

Kong Insomnia will then ask for the connection properties earlier than making an attempt a deployment for the primary time:

Since final yr, I’ve been attempting to stay by the next mission assertion, which I really feel can apply to any IT skilled:

“Focus your time on delivering options/performance which extends the worth of your mental property. Leverage frameworks, merchandise, and companies for the whole lot else.”

– J. Vester

On this article, I used Kong Insomnia to create a standardized API specification that may be totally documented, vetted, and communicated earlier than writing any supply code. This enables groups to collaborate on the design and make adjustments with out requiring any expensive service-tier updates. Clearly, this embraces my private mission assertion.

Kong Insomnia is a product that enables function groups to stay centered on extending mental property worth, contributing to the underside line positively. Taking issues a step additional, you possibly can simply deploy the outcomes from Kong Insomnia to Kong Konnect, which centralizes API specs for different shoppers to seek out and make the most of of their purposes.

In my private journey, I created lists to assist with my day by day assignments. Normally, these lists grew to become outlines, which then led to designs and specs. The API-first design sample was a pure development for me and is definitely an idea I respect and embrace.

If you’re within the unique supply code for this publication, the whole lot famous above will be discovered on the following hyperlink:

Have a extremely nice day!

More Posts