I’m currently designing a new API endpoint for marmoset. In general, there are two ways to build this: Just start with coding or start with planning. As we are smart people, of course we start with planning! There are several good ways to plan an API:
- Pen & Paper
- swagger.io
- RAML (RESTful API Modeling Language)
- Design your objects with ActiveRecord, create the API afterwords with any framework
I chose swagger in this case, but why? Swagger is a popular framework for REST APIs. I want to create a new API endpoint which meets the REST design concept so this is a good start. Swagger is also very popular in my working environment (which is another argument but not a good one).
Swagger offers an editor where you can design a yaml document which describes your API (similar to the RAML project). Defining your API in a digital way is a good thing, because this is machine-parsable, so you can use the layout later for $things. Also, you’ve now a good document which you can rely on during technical discussions with team-members. While you write the API itself, based on the document, others can start to write other applications that rely on this API, also based on the yaml notation.
Swagger’s editor has two awesome features: You can export the yaml as a basic server in several languages/frameworks, but also as a simple client. This prevents a lot of manual code typing.
Another awesome thing about swagger: You can create a fancy html UI , called Swagger UI, where you can play with the API.
How to create this? There is no creation by hand! You only need to implement a swagger lib into your project and use a good description for every method. Swagger will parse this and create the UI automatically. Why is this important? Because of another design paradigm:
There must be only one source of truth
Which means: You can write an awesome documentation for your software by hand, but it is totally useless if the software does a different thing. Creating the docs based on the real code helps to fulfill this coding paradigm.
Are you interested in swagger now? You can start their editor or host it on your own and import my API definition by URL to take a look! (also feel free to try to fix the remaining error that pops up if you parse my yaml)