Some still think that great DX is achieved by pushing API out and generating the docs with some automation tool. Yes, that might be a good start and what’s good about that is the automation part. You should automate in every corner you can in your API development workfow. The more manual work it requires the more likely someone in the process will take shortcuts which will cost you later. Don’t take shortcuts! Build proper process which relys on automation. That said, I can say a few more words about the below API workflow. It’s a simplified sketch and does not contain the details, which are always the tricky part.

Such a process is needed if you want your API development engine to work smoothly. You need to include people from various disciplines in the process and they all need to understand why and how we do API development. Actually they need to do more than understand. They need to commit to it.

Get the design right

You can’t get the design right without interacting with customers and prospect customers. They need to tell you what they need and you need to listen carefully! Furthermore they need to see it “alive” as fast as possible. Thus you need to add automated mockup APIs to the process right from the start. Of course your API designer makes the initial desing of the new API or increments to existing APIs and then you have internal review before pushing it as mockup to customers. Nevertheless in my opinion customers are eager to see how the API should work (documentation) and then actually test new features. Thus in our case we generate the candidate API (mockup) and documentation for it automatically every time “development” branch of the API design is updated.

This enables us to show always the latest candidate API documentation with mockup API next to it.

By looking at the documentation, customerers might find some holes and missign information. They give us feedback and in optimal situation after minutes the updates are available for them to see. Same applies to mockup API. AI designer modifies the API design and saves. Mockup API is updated immediately.

Implement just what is needed

After the interaction with customers around the candidate API version has been going on for a while saturation point is achieved and the most obvious obstacles from consumer’s point of view have been fixed in design. Whoaa! We have a design which satisfied the customer needs and solves their problem without causing headache. At this point API design is pushed to API developer which uses the design spec file in crafting API stub or then does diff comparison to previous version to see what needs to be changed.

Note that the API developer has the candidate API documentation to use. The API documentation looks exactly like it would be shown to API consumers. It includes the code examples on how to use the API endpoints and parameters. It contains the error handling and responses. It contains the data models to be used. In short, it’s a complete package for the developer to start implementing the API features. API developer can just give in to flow state lurking behind the corner.

During the implementation developer might face situations which require more discussions with the architect and API designer. Some things just can not be seen advance and problems need to be solved. Sometimes this requires changes in the API design as well. At this point it is fundamentally important to modify the same API design file we started with. That design file is your single source of truth. Work around the same API design file(s) instead of creating another one.

Developer integrates the needed backend and external APIS to your API endpoints. Of course there’s testing which is automated to see that all works and is done according to design. You might be tempted to just push the API to production at this point. I advise you not to.

Prepare for release

IF you are wise and witty you probably have 6-8 weeks long increments process. One increment contains sprints and after the incremention period ends, you’ll make a release. In preparing for release you need to make sure that guides which use the API at hand are also updated. Otherwise onboarding customers will be faced with guides which are not working. Guides should be the ultimate support to get newbies started and out dated guides are the best way to kill all enthusiasm and raise the bar. Most likely the newbies just give up and look for an alternative. So, prepare for the release.

If you have already built libraries on top of your APIs, you should update those as well. Keep in mind that libraries are in use and you have no way to know when the consumers actually update their libraries locally. If the changes are non-breaking, then your customers can happily keep on using the old version and update to new version gradually over time. If the changes are breaking changes, you should have similar process for the libraries as you have for retiring API versions.

From the previously patched API design you should generate the API documentation. That needs to be reviewed as well. In our case the generated code examples are automatically tested and build is not accepted if any of them fail. The same patched API design should be used in taking the API to API management.

Include marketing

Take you marketing to the process before than the illustration shows. They need to know well in advance about changes in APIs and libraries. They often have schedules for customer messages and your message should jump on the same train. They define the schedule. It’s your task as API manager to be on the right station at the right time. Otherwise the train leaves without you and you need to wait for the next one. This also means often that you need to delay the release as well.

In cooperation with the marketing prepare a marvelous blog post which also includes links to needed information such as release notes and guides as well as new shiny API documentation. They will handle the publishing and social media for you. They make sure your message is delivered to customers. Use them!

Conclusion

AS you can see, great developer experience is build with the customers. Great developer experience requires a lot of attention to more than just the technical API implementation. The more sophisticated DX you provide (code examples, libraries) the more complex the process becomes. There’s tons of things to handle! But it really pays off! Besides if you follow my advise to automate where and when ever possible, it gets lighter and efficient all the time.

Automation really is the key of sustainable developer experience.

Some more to read from 100 Days DX