Apiary Review

Produces human-readable API definitions and integrates easily with GitHub

What is our primary use case?

We are using Apiary to design APIs that we offer to our customers, brokers, and partners for insurance products. We use the product in concert with the Oracle API Platform and surface (and style) the documentation in a custom JavaScript Dev Portal. The customer's developers leverage the mock resources, the documentation, code snippets, and attribute definitions. 

How has it helped my organization?

Apiary has allowed us to produce human-readable API definitions as well as provide a common place for developers to retrieve the resource endpoints, JSON schemas, and documentation. The business-friendly definitions have allowed developers to work more closely with business stakeholders to ensure they use the APIs in the correct way.

What is most valuable?

I find the generation of mock services very useful, especially when demonstrating for new consumers. I also like how you can document many viewpoints for the same resource and easily let users navigate through these in the rendered definition.

Reuse of objects within the editor, and how easy it is to add enumerations, are also valuable features.

The ease of integration with GitHub, allowing multiple versions to run concurrently, is also an important feature.

What needs improvement?

I would like an integrated option to download a Swagger version of the definition. Currently, you can download an API Blueprint file that can be converted using other tools into OpenAPI or Swagger; however, built-in support would be ideal.

We have also used other utilities for rendering the API Blueprint, such as Agilo, for offline documentation. It would be nice if there were an option for offline documentation within the product.

For how long have I used the solution?

One year.

What do I think about the stability of the solution?

I have not experienced any downtime in the Apiary cloud.

What do I think about the scalability of the solution?

We embed the Apiary documentation in our custom developer portal and do not see scalability issues. We have seen that it is sometimes slow to render large projects, but this is not noticeable by the API consumers.

How are customer service and technical support?

Most questions are answered and product issues have been raised under the API Platform support product.

Which solution did I use previously and why did I switch?

Prior to this solution, we used Swagger and manual documentation.

How was the initial setup?

It is very quick and easy to get started.

What about the implementation team?

We implemented this solution in-house, relying on GitHub and Wiki pages for support on the MSON schema used by Apiary.

What was our ROI?

This solution has allowed us to standardize API definitions and bring consistency into our shared components. This has reduced the effort and cost of using functionality across domains within the organization. The ROI on shared services is predicated on a good API strategy, for which Apiary is crucial.

What's my experience with pricing, setup cost, and licensing?

It is easy to get started with personal (free) accounts, but a subscription is required for additional features. These include protecting access to the documentation, linking to GitHub, and sharing editing rights amongst the team.

We have a set number of users with each API Platform subscription that we have with Oracle, and this meets our needs.

Which other solutions did I evaluate?

We looked at tools to document Swagger and considered using a combination of Confluence Wiki and Postman. Ultimately, we chose this solution.

Disclosure: I am a real user, and this review is based on my own experience and opinions.

Add a Comment