Weekly API Evangelist Governance (Guidance)
Last week I talked about the importance of capabilities, and this week I want to talk about the resources that go into these capabilities. Each Naftiko Capability is made up of a variety of resources from a mix of service providers. It is fairly easy to find raw resource on the open web from GitHub, Google, LinkedIn, and many others. Refining these resources so that they are usable as part of actual capabilities takes an equal mix of standards, automation, and manual refinement. This is what I spent my week doing, with the following thoughts moving from one week into the next.
Certified Resources
When it comes to the digital capabilities I use to run Naftiko and API Evangelist—I need them to be certified. I need modular, reusable, and executable capabilities that are deterministic, reliable, and just work. This work takes a mix of open source API standards, with a minimal viable definition of what I need to produce a more refined resource that I can use across the many different capabilities I need to do business.
A Valid APIs.json
Each resource is defined using APIs.json. Certified resources defined as modular reusable APIs.json allows me to package up the technical, business, and political details I need to automate, but also in many cases manually accomplish each job that I need done. The first thing I always do is validate each resource defined as APIs.json using the JSON Schema for the APIs.json specification.
A Valid OpenAPI
Each individual resource has a single OpenAPI describing the surface area of the request and response. The OpenAPI has a single path, method, and operation, with a single 2xx, 4xx, and 5xx to support any integration using the resource. The second thing I always do is validate the OpenAPI used as part of an API resource using the JSON Schema for the OpenAPI specification.
OpenAPI Properties
A certified resource must have all of the OpenAPI properties you need to execute a request to the API resource. Each resource must have the server, operations, schemas, examples, and security schemes required to understand what is required to make an API request and validate the response using JSON Schema.
Servers - The servers where you will make a successful API request.
Server Variables - Any variables required to assemble server URL.
Operations - The request and response details you will be needing.
Schemas - The JSON Schema for schema used in requests and responses.
Examples - Examples of is sent for requests and received for responses.
Security Schemes - The standard key, OAuth, or other security detail.
Common Properties
Beyond the technical details, I will required more of the business details required to properly apply any resource as part of one of my business capabilities. I will be needing a mix of essential business properties that I store using the APIs.json common property, providing human and machine-readable properties of each resource.
Documentation - A valid URL to the documentation supporting a resource.
Signup - Where you go to signup and obtain keys needed to use a resource.
Login - Where you go to login and access your keys, usage, and other data.
Plans - A machine-readable definition of plans and pricing for a resource.
Terms of Service - Where you go to access the terms of service for resource.
Privacy Policy - Where you go to access the privacy policy for each resource.
Bonus Properties
Ideally, we don’t stop there. There are some other properties of each resource that can go a long way to ensuring the quality and usefulness of a resource. I am looking for these properties to further support integration and consumption of resources which I also store as part of the common property for the APIs.json of a resource.
Authentication - A URL to where you can find more information about authentication.
Authorization - A URL to where you can find more information about authorization.
Security - A URL to further information about the security being applied to a resource.
Rate Limits - A URL to further information about the rate limits being applied to a resource.
Support - A URL to where you can receive free or paid support when using a resource.
Status - A URL to where you can see the current and historical status of each resource.
A Single Executable Resource
It takes work to provide all of the technical details needed to certify a single resource. It takes more work to make sure you have all the business details you need. Ideally all of the technical and business details are machine-readable as well as human-readable. I have long pushed for API plans and pricing to be machine-readable, and there are ways to express most of what is listed here as machine-readable. But the goal isn’t to lose the human-readable parts, just make sure we have everything equally defined as machine and human readable.
Certified resources are required for reliable capabilities. Each certified resources needs to have a test that ensures it can be re-certified daily. Each resource should have valid plans and pricing information to help in the calculation of usage costs as part of a total cost of ownership. We will continue to work to ensure we have all the human and machine-readable parts of authentication, security, rate limits, and status updates, while also working to streamline and automate the signup and login. Sadly, I don’t think it will be very easy to make the legal side of things machine-readable.
API integration will always be harder than you think, until it isn’t, and they just work. — Kin Lane, API Evangelist