We walkthrough using APIcurio, an API design editor supporting OpenAPI Spec.Having a thoroughly documented, machine-readable API is considered top of the line development. However, creating a consistent format for the API and documentation is challenging with no outside guidance or structure. In an effort to provide this structure for API creators, the OpenAPI Specification was introduced. While the specification is undoubtedly effective, it is quite verbose and therefore challenging to master.

Apicurio Studio, maintained by the Red Hat Developer Program, is a tool for designing APIs that follows the specification without requiring the developer(s) to be intimately familiar with it. It provides a GUI for defining all aspects of the API. Ultimately, Apicurio outputs both human and machine readable documentation which complies with the latest version of the OpenAPI specification. This walkthrough covers the process of designing an API with Apicurio from start to finish, and evaluates the possibility of using Apicurio in production.

Setup & Hosting

To start using Apicurio, first decide whether to self-host or use their web app. For a long-term solution, self-hosting offers the most control. The Apicurio Studio is completely open source and always available on Github. Their documentation covers the hosting requirements and installation process, which is pretty smooth thanks to the quickstart package.

For the sake of this walkthrough, the web app is perfect. Simply register an account, and log in on the Apicurio site. No installation is required, and all features are available.

Creating an API in Apicurio

This walkthrough covers the process of building an API for a nutrition tracking app. The API needs to allow for the creation of entries in the app, which can be edited, deleted and queried. It also needs a database containing nutritional information about ingredients, which will also be accessible via API.

To start designing this API, first create a new API from the Apicurio dashboard. On the API creation screen, you can select the type (aka the OpenAPI version number), and provide a name and description.

Once the API is created, click the edit API button. The first section within the editor contains the overview information for the API. Much of this information is pretty basic metadata, like the version number and contact information. Various open source licenses for the API can also be specified on this screen.

A few sections are worth noting as they’ll come into play later when defining the primary functionality of the API: these are the server and security definitions. This data is used when creating the paths later on. Security definitions include standard options like an API key or OAuth, which can be implemented as requirements.

One or more servers may also be created, for example a production and a development server. Server variables are built-in, and can be used to define things like the port number or API version. Take care to include defaults for all server variables, or an error will be thrown.

Adding API Definitions

Once the API is created, the next step is adding some basic definitions. Notice here that what the OpenAPI specification calls Media Type Objects, Apicurio calls definitions. In this nutrition tracking API example, two definitions are required. One will define the structure of an Entry in the journal, and another will define the structure of an Ingredient found in the database.

To add a definition, click the button and specify a name. From there, simply add the required properties to the definition. When adding a property, first add the name. Then click into the property to edit it and flesh out the information. Properties can be marked as required, and their type and formatting can be specified from a list of OpenAPI-approved options such as strings, booleans, and arrays.

The ingredient definition also receives a few additional properties, like calories (a floating point number), serving size (a string), and an associated image (a string). The Entry definition is created just like the ingredient definition, by adding properties like the date (a date formatted string) and name (a string) of the Entry.

Most properties are quite simple, but it’s worth noting that one definition may reference another definition. In the case of an Entry, one property (ingredients) is an array of Ingredient objects referencing the earlier definition.

Adding API Paths

Once the definitions are created, move on to creating API paths. Paths specify all the different endpoints of the API, and the operations which take place at the different paths. While definitions are relatively simple, paths contain many layers of information. Not only are the paths specified, but requests and responses are outlined, security and servers are implemented, query parameters are provided, and much more.

To add a path, just click the link and specify the url of the path. The first one in this nutrition example is /entries/, which will by default return the 5 most recent Entry items submitted by the user. On the edit screen for this path, first specify any applicable operations. In this case it’s simply a GET operation to fetch the Entry items. Select GET, and add a brief description outlining the operation.

The OpenAPI specification requires all operations to at a minimum specify the response type. Click the GET link to be taken to the details screen for this operation, and then select the link to add a response. For a simple GET request, the status code is 200. From there, you can specify the description as well as the media type which is returned by the request. In the case of the /entries/ path, the returned content will be JSON containing an array of Entry items. If so desired, an example response body may be provided.

This path also supports some query parameters, which may easily be specified. Like the definition properties, the query parameters can have associated descriptions, types, formats, and be required or optional.

From here, the API paths can be versioned out to meet any needs. Other operation types include the standard PUT, POST, DELETE, and several more. The servers and security measures defined in the API overview can also be added to any path.

For some paths, parameters might be required. In this nutrition tracker, for example, a user should be able to provide a specific date and get any entries matching that date. To utilize path parameters, simply create a new path and use {} around the parameter.

Once the path is created, path parameters appears as a new section on the path design screen. Any named parameters are automatically placed into the path parameters section, but must be specifically defined. To do so, click the create button and then edit to add a description. The parameter type and format can also be selected – for this path, a string formatted as a date is the appropriate choice.

API Validation and Errors

Because Apicurio is a tool specifically for creating APIs which conform to the OpenAPI specification, validation is an important consideration. Apicurio does a nice job of highlighting any errors found throughout the API, whether it’s missing information, invalid data selection, or using features which aren’t intended to be used together.

Errors are immediately highlighted, both in the sidebar and within the problematic path or definition. In this example, a GET operation has been created for the date path, but no response has been specified. A response is a required part of any operation, according to the OpenAPI specification, so the problematic path and operation are flagged. Clicking on the tooltip reveals the error(s) in question.

An issue tracker is also available, with a list of any validation problems found in the API. Each problem includes a direct link to the issue, making for a faster resolution.

Collaboration and Publishing

More often than not, an API has a whole team behind it. Collaboration is an important aspect of any API design tool, and Apicurio Studio offers opportunities for full collaboration. Start by inviting any users, a process which annoyingly involves generating a unique url and sending it to the individual user. The user can then create an account, and accept the invitation to collaborate.

Once the user is in, collaboration is simple and straightforward. All users have the ability to edit the entire API, and all changes are posted in an activity feed. This ensures all changes can be traced back to the original user, in case of questions or concerns.

Upon completion of the API design, a few options are available for exporting or publishing the API. These options are tucked away in the menu on the API overview screen. Machine-readable YAML and JSON can be downloaded directly, or code can be published in a linked repository (e.g. Github or BitBucket).

The most exciting option (still very much in beta) is the ability to generate a working project. This project includes a bootstrapped implementation of the specified API, providing a small foundation which is particularly useful for demos and MVPs. Currently projects are limited to Thorntail Jax-RS, but future options include Node.js and Vert.x.

The Good and the Bad

Apicurio Studio has many features worth highlighting. It is a strong tool for brainstorming and designing an API before the actual development begins. Apicurio helps the team to really think through the whole API and make sure that every aspect is considered. Once the tool is up and running, and a bit of familiarity has been established, it’s quite easy to use. The collaboration process is simple, but effective. The owner of the API maintains control of all approved collaborators, but otherwise everyone can freely edit. The activity feed provides just enough information, without having to spend time configuring it.

Considering how dense the OpenAPI specification is, Apicurio is a welcome alternative to getting totally familiar with it. The error validation and issue tracking is clear throughout the entire design process and ensures that specification compliance is appropriately enforced. The end result is completely in line with the specification, and building in these requirements contributes to the effectiveness of Apicurio as a brainstorming and design tool.

Apicurio is also free and open source. The code is always available on Github, and it is quite regularly maintained. The team averages one or two updates per month, to ensure continued OpenAPI compliance and to publish new features.

That said, it’s not all perfect in Apicurio. While it is quite feature-rich, the UI could use a bit of polish, particularly for new users. Including tooltips or an initial walkthrough of the interface would help point out how the application should be used and what different terms mean. Linking off to outside resources is also a good option.

Another recurring problem was deeply hidden features. Many important items are tucked into the various menus, and it is challenging to remember which menu on which screen contains the desired feature. This can lead to some unnecessary effort, like manually replicating paths when a clone option does indeed exist.

Finally, the collaboration flow could be a bit smoother. Generating a link which isn’t associated with a specific email address is confusing. Manually creating and sending the invitation email is also a sub-par experience. While it’s understandable that a free and open source tool might not want to pay for server resources to send the emails, opening up a pre-populated email message on the user’s machine and associating invitations with particular emails would help.

Final Analysis

Apicurio has a lot to offer, and is a strong contender in the domain of API design tools. While it could undoubtedly use a bit of UI polish (and perhaps a day of usability testing), the structure and validation helps guide the design process. Apicurio forces collaborators to consider all aspects of every path and definition. The end result is therefore far more thought out than simply developing the API live and then retroactively documenting it.

Have you utilized Apicurio for an API project? Share your thoughts (good and bad) below.

This post is part of our effort to review emerging API related tech, and was not sponsored at all. If you would like to share your project with us, feel free to contact us here.