HACKER Q&A
📣 andrewtsaplin

How do you design/review/publish your back end API?


I'm in a process of finding right tools to design, collaborate with my team and then publish documentation about my backend APIs.

Share you experience & great tools you using for API design workflow.


  👤 smt88 Accepted Answer ✓
I've built ~12 web APIs in the last few years across various languages (TypeScript, C#, and Kotlin).

You should always design first. I'm a longtime Open API Spec user, so I build the spec from scratch in Apicurio Studio or Stoplight. (I highly recommend keeping it in JSON, as the YAML specs are horrendous to read/edit.)

If you're very attached to your language of choice, there are usually tools you can use to annotate your data models and controller classes, and then you can generate your Open API Spec file from there.

The benefit of all this is that your public docs are programmatically bound to your type system (hopefully, assuming you're using a strongly typed language). If your spec changes, your code won't compile anymore.

You can also use your spec file to generate models/controllers (if you did spec-first instead of the annotation option), as well as unit tests. You can import it into Postman. It's very useful.

So our compile process is something like:

1. Lint the Open API Spec file with something like Spectral

2. Generate models and controllers from Open API Spec (which are imported as base classes and are not modified by humans)

3. Compile

Unfortunately, the existing generation of model generators for C# don't handle null well, so you lose out a huge benefit of the strong typing. TypeScript and Kotlin are fantastic about that, though. In general, I would recommend Kotlin today because it has the best combination of ecosystem and language, whereas C# has a great ecosystem but frustrating nominal typing system (until C# 9 anyway) and TypeScript is built on the shantytown that is JavaScript/npm.


👤 solodev1
Adhering to OpenApi 3.0 spec https://swagger.io/docs/specification/about/ you will be able to take advantage of plenty of tools available to you, regardless of the programming language/framework chosen to build your software.

It's not always possible or desirable to have back-end models and controllers auto-generated from OpenApi spec, but still I totally recommend to make an extra effort to keep documentation and API in sync since day 1 as API is evolving.

Document an API it's definitely not an easy task, but it pays off - specially if you plan to have third-party developers consuming your API in the future beyond your own engineering team.

Some important points I try to be disciplined about, based on my own experience building APIs in C#, Delphi, Go, Java, Node.js, PHP, Python and Ruby:

1) Document your API from day 1

2) Update your API docs every time you commit a new change to your models/controllers/endpoints

3) Test your API docs against your actual implementation. Dredd is a great tool for that: https://github.com/apiaryio/dredd

4) Build an API client from day one (web app, command line app, desktop app, whatever), and use it for testing the consumption of your API endpoints, and update it every time your API changes

* Benefits: you're gonna have a perception of the developer experience that your API users are going to have when consuming it, and very likely that will bring you some insights on opportunities to make things simpler or better documented (header params, query params, request payloads, endpoints signature, response status codes, ...)