Schema Should Be as Important as API Definitions
Most API documentation fails to provide a schema for the underlying data within the interface. Hopefully, this is something that can be improved upon this year.
Join the DZone community and get the full member experience.Join For Free
The importance of a machine-readable API definition has grown significantly over the last couple of years, with a lot of attention being spent (rightfully so) on helping educate API providers of the value of having an OpenAPI Spec, an API Blueprint, or another format. This is something I want to continue contributing to in 2017, but I also want to also shine a light on the importance of having your data schema well defined.
When you look through the documentation of many API providers, some of them provide an example request that might give hints at the underlying data model; however, you rarely ever see API providers openly sharing their schema in any usable format. You do come across some of a complete OpenAPI Spec or API Blueprints from time to time, but usually, when you find API definitions, the schema definition portion is incomplete.
Not having your schema well-defined, shareable, and machine-readable is one of the contributing factors to a lack of common, shared schema in the API space. We have healthy examples of this in action with Schema.org, but for some reason, many of us don't bring schema front-and-center in our API operations. We are accepting them as input for our API requests and returning them with API responses, but we don't always share examples of this in our documentation, complete sections in our API definitions, or share JSON Schema as part of our developer resources. This all contributes to a lack of consistency within a single API operation, as well as the wider industry.
I am going to spend more time in 2017 talking to people about the schema that they use in their API operations and shining a light on existing schema that has been published by API providers. I will be also continuing to support important schema like Open Referral that helps streamline how our world works. It is no secret that when we speak using common schema, things work smoother and that we will make sense to a wider audience. I hope that in 2017, we can invest more in defining and sharing the schema we put to use and reusing some the most common examples out there.
Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.