API First Development

An extension of “Design-First” methodology is “Contract-First” where the developer defines the contract of the API before the implementation is coded. Just-in-time and just-enough design is critical to agility. Applying design-first / contact-first methodology to the world of API development results in “API-First” development. The basic idea is that you create an API contract before implementing the full code and plumbing. The human-readable API specification becomes the quick first deliverable that allows fast, quick feedback from various stakeholders. These rapid iterations are a game changer because changing the API specification takes minutes not hours or days! Once the team determines that the API specification is “good enough” a full maven Spring Boot Application can be generated. Many other languages are supported as well – more on that later. The developer codes the business logic implementation in the server stub. While the developer is coding, the QA teams can be handed the spec as well so they get a head start on service testing.

API First with Open API Spec 2.0

The Open API Specification is a language and vendor neutral API specification standard. There are many permutations of tools, technologies, languages to approach API design and development, most new server-side development happens in the Java programming language. This document will walk through a real world scenario of putting ‘API-First in Practice’ with Open API for the first time. The goal is to provide a clear path to achieving agile API development and being effective at it.

API-First Development Workflow

There are 4 high-level steps:

Create API

Collaborate

Generate Server

Deploy to Cloud

The first step is essentially starting the API development using Open API Spec 2.0. Begin working on evolving and iterating the API specification by collaborating with the product owner, service consumers and other stakeholders. Once the team is comfortable that the API specification is 'good enough' - generate the server in Spring Boot. Deploy the app to the cloud or locally. At this point the round-trip engineering starts. All updates to the API in the code automatically updates the API specification that is co-deployed via annotations.

Step 1: Create the API

Use Open API 2.0 specification standard and the YAML format to describe the API as follows:

Expect the consumers of the API to read the info sections, paths, verbs and model information to fully understand the API and how to interact with it.

'swagger' - This snippet is the defacto standard - the swagger version (which is Open API Spec 2.0)

'info' - this specifies high level information about the api

'title' - Ensure that the title is clear and broad enough that it covers the API as whole.

Defining the Paths

paths:/transactions:post:summary:|Startsatransaction.ItcanstarteitheraMulti-lineApporaMono-lineAppTransaction.AlltypesoftransactiontypesaresupportedviathisAPI.Businessrules/logicwillbeexecutedtoensurethisoperationcanbeexecuted.Transactionsareacontainerthattracksandmanagestheoverallprocessing.description:|ThisistheaggregaterootoftheAPI.IfonlyoneLOBrequestexistsunderthetransactionthenamonolineapprequestiscreated.Amulti-lineapprequestcontainsmorethanone'lob requests'. Each 'lob request' has an associated policy app/lob. This end-point contains a single request or multiple requests - and executes the StartRequestCommand.TheMultilineRequestendpointcreatesanewmulti-lineapprequest(andchildrequestsifprovided).ThisAPIshouldbeusedforallrequests(monolineappormulti-lineapps).ThisistheMulti-LineAppRequestAggregateRoot.consumes:-application/json-application/xmlproduces:-application/json-application/xmlparameters:-in:bodyname:transactiondescription:|Ifatransaction_idisnotprovided,onewillbecreatedbytheservice.Accountisoptional.Agencyisoptional.Thesecanbeaddedtothetransactionlater.required:trueschema:$ref:"#/definitions/Transaction"tags:-Transactionresponses:200:description:Successfuladditionofatransaction.400:description:Invalidrequestreceived-pleasechecktheAPIContract.403:description:Forbidden.Clientisnotpermittedtoperformthisoperation.409:description:Conflict.Resourcealreadyexists.default:description:Unexpectederrorschema:$ref:'#/definitions/Error'

The path parameters define the shape of the API via URIs. Each URI definition has multiple HTTP verbs that can act on it.

POST: has a summary of what the API expects and what it responds with on a creation.

Summary and description fields are important to document so that the consumer of the API knows how to use it.

Consumes & Produces - specifies the data formats the API will accept and produce.
the Parameters specify where and how the data will enter the API e.g. body, path, header, query etc.

tags - these are optional but help in the documentation of the API.

responses - the responses specify how the API responds and what's in the response body.

definitions - Define the models in the definitions - this section is typically at the end of the API spec file.

You can start the Open API 2.0 Editor here
It will start up with an example. Alternatively, you can import another YAML specification - see the YAML specifications in the references section.

Step 2: Evolve the API (Collaborate)

As the API is developing - the specification file can and should be shared with other collaborators for review. The main idea is to ensure that the paths and models are good enough. In other words, you don't want to strive for perfection rather a few brief meetings with the stakeholders to ensure that there is a common understanding and consensus. The idea is that API-first allows for rapid iterations without changing the code/plumbing in the initial phases.

The first-cut of the API spec should minimally have the RESTful paths, responses and high level response objects. The API should be small-enough that it fits within a person’s head. Of course, good understanding of domain driven design, API design, REST design and Open API spec is required.

This design spec can save you hours of implementation and refactoring effort in the plumbing of the code. This allows subject matter experts to discuss the API and make changes. Quality engineers can get involved and begin early test design and development. Architects can begin to think about system architecture implications on sourcing of data. Data analysts can begin thinking about data fields and standards alignment where appropriate. This spec should become the camp fire across which multiple teams can gather to discuss the API and make changes.

Step 3: Generate Server Stub (Spring Boot Scaffolding)

To further accelerate the API development process, go ahead and use the API Editor to Generate the Server. Alternatively a command line tool can be used.

A 'Spring Boot' server gets generated along with a Maven pom file and it's dependencies. A compressed zip file with all the scaffolding code for the API is downloaded.

This can be expanded and imported as a Maven project. The parent pom should be updated. Package names should be renamed to match the needs of the service.

The project already contains a Maven pom file and a Spring Boot project with dependencies. it can be run as-is and deployed - it just works. Open a command terminal mvn spring-boot:run .

Step 4: Implement and Deploy

When you run the Spring Boot API - you will see the Annotations have been added to the code - and they show up via the api-docs and also the swagger ui.

This api is a JSON format that represents the exact YAML file that was written. Going forward as the code is changed to evolve the shape of the API and it's implementation, SpringFox annotations in the code will always keep the API in sync. If new API end-points are added to this or new verbs - the developer is expected to use the annotations. This should be simple because the API interface class already has annotations and following the same conventions over time will be much easier.

A user-friendly and interactive Web-Page is generated automatically (Swagger UI). This allows for a quick execution of the API - the web-form allows for data to be entered directly and this allows the API to be tested quickly by any user without any special tools or technology skillsets.

Conclusion

There are many permutations of tools, technologies, languages and methods that try to approach API design and development. Weeks of microservices coding can save you hours of API designing. The goal is to provide a clear path to achieving API-First development and being effective at it. API-First Development practice as outlined in this document is effective and economical.