Over a million developers have joined DZone.

Keeping API Schema Simple for Wider Adoption

DZone's Guide to

Keeping API Schema Simple for Wider Adoption

Allowing business users to easily work with your API will lead to a higher adoption rate and a greater impact. Read on to see how this can be achieved.

· Integration Zone ·
Free Resource

WSO2 is the only open source vendor to be named a leader in The Forrester Wave™: API Management Solutions, Q4 2018 Report. Download the report now or try out our product for free.

One aspect of my talk at APIDays Paris, included a slide about allowing API consumers to negotiate CSV responses from our API. Something that would probably NEVER occur to most API providers, and probably would make many even laugh at me. I’m used to it and don’t care. While it's not something that every API provider should consider doing, depending on the data you are serving up, and who your target API consumers are, it is something that might make sense. Allowing for the negotiation of CSV responses represents lowering the bar for API consumption, and widening the audience who can put our APIs to work.

I was doing more work around public data recently and was introduced to an interesting look at some lessons from developing open data standards. I’m doing a deep dive into municipal data lately as part of my partnership with Streamdata.io, and I found the lessons they published interesting, and something that reflects my stance on API content negotiation.

From the development and maintenance of the API, it quickly became clear that adjusting scripts after every election (and by-election) and website modification, was quickly becoming unsustainable. To address this issue, a simple CSV schema was developed to encourage standardization of this data from the outset. The schema was designed to be as simple and easy to understand and implement as possible. Comprised of just 21 fields, 7 of which are recommended fields, the schema does not have hierarchical relationships between terms and can be implemented in a single CSV file. By making the standard this simple, we were able to get a number of adopters onboard and outputting their lists of elected representatives on their own open data portals.

When it comes to APIs, simplicity rules. The simpler you can make your API, the more impact you will make. Allowing for the negotiation of CSV responses from your API when possible allows API consumers to go from API to a spreadsheet in just one or two clicks. This is huge when it comes to onboarding business users with the concepts of APIs, and what they do, and allows them to easily put valuable data resources to work in their native environment–the spreadsheet. This is something many API consumers won’t understand, but when it comes to seeking meaningful API adoption, it is something that expands the reach of any API beyond the developer class, putting it within reach of business users.

I am a big fan of pushing our APIs to allow for the negotiation of CSV, XML, and JSON by default, whenever possible. I’m also a fan of delivering richer experiences by allowing for the negotiation of hypermedia media types. While delivering hypermedia takes a significant amount of thought and investment, allowing for the negotiation of CSV, XML, and JSON doesn’t take a lot of work. When delivering your APIs, I highly recommend thinking about who your API consumers are, and whether offering CSV responses might shift the landscape even a little bit, making your valuable data resources a little more usable by business users who won’t necessarily be delivering web or mobile applications.

IAM is now more than a security project. It’s an enabler for an integration agile enterprise. If you’re currently evaluating an identity solution or exploring IAM, join this webinar.

integration ,api ,api consumers

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}