Describe your API, or Here comes Apiary

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.


About Maryna Cherniavska

I have productively spent 10+ years in IT industry, designing, developing, building and deploying desktop and web applications, designing database structures and otherwise proving that females have a place among software developers. And this is a good place.
This entry was posted in Programming, tools, Uncategorized and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s