Save Time with Design Time REST APIs
We've all been guilty of thinking we know what's best for somebody else, whether it's our political opinion on abortion or suggesting that others really shouldn't watch that new Star Wars movie. We do this all the time when we design software, particularly with APIs. We will get the requirements for an API, craft an outline of what it should look like, then start coding it. We end up with this absolutely beautiful and clean REST API that no one could possibly say anything bad about. When it comes time to release our masterpiece, the users (other developers) hate it.
But why?
We set ourselves up for failure from the get-go when we assume that other developers are just like us. Sure, that developer who will consume our API has a similar skill set to us (maybe they are even our clone!), but the way they need to use this API could be totally different from how we imagined them using it. Maybe they are working with legacy software? Maybe the requirements changed on them, but we never got that update? Maybe they just came up with an alternative design for their app that we never considered?
Where we failed
Maybe we were so confident in ourselves that we just coded the API immediately. By the time we finally showed the API to the other developers, we had already spent several days on it only to find out it didn't fit their needs. Whoops. Now we spend a couple more days making the changes they need only for them to request even more changes. This repeats and we incur the cost of our time, the other developers' time, as well as the opportunity cost.
Maybe we were a bit smarter and decided we should design our API on whiteboard/paper at first. Now we think we have a solid foundation, but we still don't know if the user will actually like what we designed. We're back in the situation where we were before; code, feedback, code, feedback, and so on. We're still wasting just as many resources as before; possibly even more because we spent that extra time designing something they didn't even want!
How we can improve
Instead, we should design and seek feedback immediately. Sure, we could discuss the whiteboard/paper design with our developer users, but as I've stressed, they don't know what they want until they have something real to play with. Let's give them a mock API to implement against. Instead of spending a lot of time coding up the solution against databases and working out complicated business logic, simply provide the interfaces, routes, and mock data. We can whip out a mock API in a small fraction of the time it would take to build a fully integrated solution.
Now we have a lot of flexibility we didn't have before. Our beta of the API is out within hours instead of days, meaning the developer users can immediately play with it and give feedback. Just as important, we can make the changes they request even faster. We can iterate through several designs in a single day instead of a few designs over several days/weeks. We'll land on a better solution in less time.
We also get the (important) side effect of being able to develop in parallel once the mock API design is finalized. Our users can code against the mock API while we build the business logic in the background.
Implementation and Tools
You certainly could roll the API in your favorite framework and manually write the mock data, but there are better options.
My favorite is SwaggerHub. Here you use the Swagger/OpenAPI spec to declare the interfaces, routes (URI, Verbs, HTTP Responses), and behavior you want your API to have. It's fairly intuitive and you can check out the Getting Started With SwaggerHub guide.
After you design it, you can download a skeleton project for your favorite server (aspnet-core, Node, Go, etc.) and client (Angular, Ruby, C# MVC, etc.). Let SwaggerHub write the boilerplate code for you.
You may argue: "However, I had to spend time writing that Swagger/OpenAPI document!". Here's where it gets good: each time you need to make changes, just modify the Swagger/OpenAPI design and redownload the new project. Bam, easy!
Wrap it up
The key here is to spend less time coding and more time designing and receiving feedback. We already know that's what we should do, but we don't always know how to do that. Hopefully, this can help speed up your API development.