I drafted a simplified presentation of Design and customer driven API development. I had to do it for one academic article I’m writing to 42nd International Conference on Software Engineering, so it makes sense to write about it this series as well. Here it is. If you are familiar with Lean thinking and API development (with design), there’s probably nothing new.

It all starts from the customer

API development starts from the customer (developer). They have needs and means to express their feature requests to API provider. The feedback channel starts from the obvious spots in the developer’s path like API documentation. You offer easy access to feedback by adding links to API documentation instead of directing the developer to separate page where you inform them to write email to you. Simplest option is to use custom issue templates in Github so you can add labels in the issue on behalf of the customer and prefill the issue template with topics and instruction. Publishin the feature requests have a lot of benefits. First, rest of the developers can see the requests made by others. Secondly, others can thumbs up the issues reported already or add more comments and notes. Thirdly, opening up the “wishlist” will gently push your customer support to handle it properly and promptly since the customers are looking at you.

Processing of the needs

Someone has to be responsible for handling the feedback. One of the crucial decisions to be made is whether the feature request will cause breaking change or not. You need to have own processes for both or otherwise you will end up breaking the applications build on top of the APIs all the time. The API designer has to evaluate the request if it relates to something already existing design change or not.

On-going design

This is on-going process even if the following implementation would be sprint driven. The companies with plenty of APIs most likely have API Design Guide to assist the designer in converting the request to API design. API Design Guide contains practices for paramater and endpoint naming, defines what is counted as breaking change, error handling among other things. In Design driven API development API design is written in the form of machine-readable API specification such as popular OpenAPI spec (REST APIs).

In ideal situation machine-readable spec is just a tool and design is actually API documentation driven. API designer is able to see the final documentation while designing the API. This approach ensures the customer centric viewpoint in the process since designer sees the API through the eyes of the consumer as they would actually see it eventually.

Designer can use tools to generate mockup APIs from the spec automatically. With help of the mockup APIs it can be tested without using any resources to write single line of code. Sample code can be written and tested agains the mockup API to verify that the developer experience regarding endpoints and parameter is optimal for the API consumers. The mockup API can be given to API consumers for review and testing. Based on the feedback API designer adjusts the API design. The process is continued as long as feedback stops or available time is up.

At some point there’s enough changes in the API or APIs and development can be pushed forward. Depending of your general development process the changes might be packed in to one two week sprint.

Implementation

Somwewhat in parallel with finalising the API design changes, architecture limitations have to be checked to see that wanted features can be implemented. At the final stages of the design process, QA is included to verify and review the design. QA team often also has good hunch of the implementation and might even bring in the tech team lead in the review process. This review and discussion driven handover process is crucial since regardles of additional documentation tacit knowledge is in the designer’s head.

After that depending of your organisation’s development practices, you first write the tests against which the API implementation is developed. Machine-readable API spec can be used in the step as well. There’s plethora of tools to generate API stub code from the spec file to minimise boring API frame development. After that developer adds the code for logic or integrates the API to another public API. One or another the backend is developed or taken into use with help of internal, partner or public APIs. Nevertheless this is the step when backend is taken into the process.

Deployment

Before the API can be deployed the final tests are executed and generated API documentation checked. If the API is part of larger platform, the related getting started guides have to be updated. Also if support for additional tools for example API testing (Postman, Insomnia) are provided, then the packages must be updated as well. Depending of your release management, code is eventually automatically or manually released to production after passing testing and staging environments.

Notify customers

You might have good API now in production, but nobody knows about the new features. You have to inform the consumers about the changes. Still the most reliable communication method towards the API consumers (developers) is email. You can send automatically or manually update to all or selected customers. In the same message you gently remind of the available feedback channels. After this you can close the related issues in your public wishlist. Definition of done is reached and cycle continues to next round.

Some more to read from 100 Days DX