There’s an interesting service out there called Apiary which I think was quite underutilized by us, because I only used it a few times in my work. The importance of it, however, was recently proved by it having been bought by Oracle – which isn’t an ordinary achievement, especially for a tool with seemingly little commercial value. So, what is Apiary? In a few words, it’s a solution that lets you describe the API you’re designing.
However, it goes much further than that.
Basically, the Apiary workflow is as follows:
- You write the API description using either the API Blueprint or Swagger syntax;
- You share the documentation and collaborate on it;
- You show how it works using the Mock Server API calls without writing any code;
- You use API Inspector to see exactly what kind of traffic you produce and receive.
Rinse and repeat, and after a few iterations you have a perfectly prepared specification, which you can use as a template for your real implementation.
Of course, there’s still a lot of places where things can go wrong, but one of the most frustrating things in API design is not getting the requirements right and not building exactly what your client wants from you. This is where Apiary comes in to save the day and make sure that your design really goes hand in hand with the requirements. After that, of course, it’s your task to make sure that your implementation is mirroring your design… but that is already an entirely different story.