Preparing For Conversations About Schema, Definitions And Scopes

02 Feb 2017

I am focusing heavily on schema, definitions, and scopes in 2017, because it is the most important layer in the tech sector, the API space, and is something that touches almost every industry, while also reaching into our personal worlds. I'm working on refining my argument in 2017 that I'm not selling APIs as a solution all by themselves, I'm pushing APIs to help us tame this insane beast that we've let out of the closet, and will never be able to put back in.

SchemaWhether it is JSON schema, MSON or Data Packages, current approaches to defining the data used as part of each API request or response are defining what has become to be known as the API economy (for good and bad). The schema describes the digital bits that are being created and moved around online today. They are the videos, images, blog posts, messages, and other digital elements that make up our online business and personal worlds.

Defining schema are critical to platforms working properly, and having them in a machine readable way allows for them to be shared between platforms, providers, and applications. Defining these bits allows us to have a conversation about these bits, which can also open up the conversation about whether or not we should be collecting, storing, and sharing these bits in the first place. I know many tech people don't want to have these conversations outside their inner circles, but we should--it is important for all of this to work for everyone.

DefinitionsAPI specification formats like OpenAPI Spec and API Blueprint have emerged to give us a way to define the surface area of APIs that are used across web, mobile, and device applications. These specification formats are allowing us to define, describe, and have a conversation around the valuable data, content, and algorithmic resources being made available via APIs using the web. The resulting API definitions are currently being used by companies as part of every stop along the application and API lifecycle, from design to deprecation.

API definitions allow us to describe the access available with the data, content, and algorithmic resources that we are depending on in our daily business and personal worlds. API definitions describe the request and response model for each API resource but also describes whether it is just readable, writeable, as well as updated, and able to be deleted. These definitions are being used to quantify what access is available in almost every aspect of our increasingly digital lives.

Scopes "OAuth is an open standard for authorization, commonly used as a way for Internet users to authorize websites or applications to access their information on other websites but without giving them the passwords." OAuth scopes are the negotiated definition between each platform provider, end-users whose data that is being made available, and the 3rd party developer, application, and systems that will be putting the content, and data to work. In 2017, platforms like Slack are getting better at sharing their OAuth scopes in the same way that schema and definitions are being shared, making them an important part of the conversation.

I have sat with the Department of Energy and power companies, Health & Human Services and healthcare software manufacturers, negotiating the OAuth scopes for energy and healthcare data. The most familiar examples of this in action is when it comes to access your Facebook or Twitter social data, but it is a model that works across any content, data, and algorithms being made available on the web, in a secure way. OAuth scopes determine the 3-way relationship between providers, developers, and end-users, and make the process of sharing more secure, while also making sure all participating parties have a voice in the conversations, potentially at a granular level.

Schema, Definitions, and ScopesI do not evangelize APIs because the technology fixes things. I do not believe in techno-solutionism. Internet technology is here, and we have to deal with it. My objectives around APIs is to make things more observable, and I feel that schema gives us the opportunity to define what bits are being collected, stored, and moved around the web. API definitions give us the opportunity define what access there is to these bits, and where you GET this access, and when the opportunities for reading and writing are as well. Finally, scopes allow us to define exactly who has access to these bits, and most importantly, we are doing it in a way that gives the owners of the bits (end-users) a voice in the conversation.

This is why I'm focusing on the schema, definitions, and scope so heavily. They alone aren't a solution by themselves, but when you properly define, share, and them up to all stakeholders involved, the potential for equity is greater. The problem is that platforms do not always want to share, as the resources being made available are key to their revenue generation, and developers often see these bits in a similar light, and all of this happens in such a technical way, behind the scenes that end-users are often left out completely. When APIs are done right, and schema, definitions, and scopes are properly defined, and available to everyone in an easy to follow, yet machine readable way, things have the possibility to work out much better for everyone involved.