OpenAPI Will Help You Get Your API House In Order

January 11, 2018

I wrote a piece previously about Consul not supporting Swagger documentation at this time, and the API provider and consumer impact of this decision. I’m going to continue picking on Consul with another API definition story, because they are forcing me to hand-craft my own OpenAPI. If I just had to learn about the API, and load the OpenAPI (fka Swagger) definition into my postman, publish to the repo for the project, and import into other tooling I’m using, I wouldn’t be so critical. However, since I’m having to take their static, and often incomplete documentation, and generate an OpenAPI for my project, I’m going to vent some about their API and schema design, and they short-sighted view of OpenAPI (cough, cough fka Swagger).

I just finished an OpenAPI for the Consul ACLs API path, and currently working on one for the Agent API path. I have already distilled down their static documentation into something that I can easily parse and translate into OpenAPI, I just need to finish doing the manual work. It is something I normally do with a scrape script, but the difficulties in consistently parsing their docs, combined with the scope of the docs, made me go with hand-crafting after distilling down the documentation for easier handling. I am familiar with the entire surface area of the Consul API, and now I’m getting to it’s intimate details, which also includes it’s intimate lack of details.

The first area I begin stumbling on is with the design of the Consul API. While it is a web or HTTP API, it isn’t following most of the basics of REST, which would significantly help things be a little more intuitive. Simple examples of this in action would be with the LAN Coordinates for a node path, which is a PUT with the following path /coordinate/update – making for verb redundancy in the HTTP Verb and path. There also isn’t a consistent approach to ids and how they are used in the paths, which is a side effect of no real focus on resources, or use of REST principles. Ultimately the API design isn’t as bad as many APIs that I consume, but it’s inconsistencies does it make it difficult to learn about.

The next area I find myself stumbling with is when it comes to the schema and response structure for the Consul API. In the documentation, some APIs provide no insight on what schema is returned, while others show a sample response, and others actually providing detail on the fields, types, and description. Some paths will utilize the same schema, but only reference the need for part of it, and return only what it needs, with no consistency in how it does this. Again, a lack of coherency around any resource model, and just requesting and responding with what is perceived in the moment. The challenge is not all of us new developers are “in the moment”, and the lack of consistency makes it difficult to understand just exactly what is going on.

As I mentioned in my previous piece, OpenAPI (fka Swagger) is much, much more than just API documentation. In this example, if present, it would act as a design scaffolding for Consul to think through the overall design patterns they use for each of their APIs and their paths, as well as consistently using the schema across the request and response structure of each API. The only reason I’m writing this story is become I needed a break from documenting the inconsistent details of the API. Piecing together a complete picture of the schema from one piece over here, and one piece over there, just so I can learn about the API and put it to use correctly in a project. I’ve read 100% of their API documentation, and hand-crafted an OpenAPI for about 30% of your API, and now I’m wishing the Consul had embarked on this journey, instead of me.

OpenAPI is much, much more than just documentation. It would give that strategic polish to a very tactically designed API. The dismissal of OpenAPI, because they’ve already done API documentation is just one symptom of a very tactically operated API. If Consul had used OpenAPI, it would have given them scaffolding to help them get their API house in order. It would have allowed them to think through the details of their API, which now as a consumer I’m having to do, and provide feedback on, which will hopefully would get included into the next version. With OpenAPI you have the opportunity to expedite this feedback loop, and see the missing details yourself, or potentially mock and provide the interface to a select group of users to provide feedback before you ever begin development.

My frustration with the Consul API isn’t entirely the design of it. It is mostly the incomplete design of it, and their unwillingness to pick up their head and look around, understanding what is good design, as well as what OpenAPI (fka Swagger) is, before responding that they don’t support it. I’m going to keep hand-crafting my Consul OpenAPI, because I see the value of the service, even if I don’t like their API, or the efforts that was put into the API. I’m hoping that they’ll see the light with OpenAPI, and maybe my hand-crafted edition will turn on this light. If nothing else, at least it will provide an OpenAPI that other developers can use, even if Hashicorp’s Consult team doesn’t see the value.

Read more...

Previous Article
OpenAPI Will Help You Get Your API House In Order
OpenAPI Will Help You Get Your API House In Order

I wrote a piece previously about Consul not supporting Swagger documentation at this time, and the API pro...

Next Article
Working With General Transit Feed Specification(GTFS) Realtime Data
Working With General Transit Feed Specification(GTFS) Realtime Data

I’ve been diving into the world of transit data, and learning more about GTFS and GTFS Realtime, two of th...