Need help?
Contact us
Chat with Kin
AI assistant · trained on my blog
A base URL is the APIs.json property for each API that takes applications to where the API resources are available via simple paths. The base URL is used across all of the API requests that any con...
API Commons is one of those areas of API specifications and standards that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than mo...
API Descriptions is one of those areas of how descriptions are used across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details...
Design-first is a methodology for delivering APIs that begins with defining an OpenAPI specification, documenting, and mocking the API. This allows teams to iterate on the design with stakeholders ...
A human URL is the APIs.json property for each API that takes people to a landing page dedicated to an API. Often times this is redundant with documentation for an API, but ideally is a dedicated l...
API Identifier is one of those areas of unique identifiers across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
Providing a simple icon or image for each individual API helps enrich the metadata that will be used to distribute and publish APIs to portals, directories, and catalogs. Images provide a simple wa...
API Images is one of those areas of images and visual identity for APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
The metadata for each individual API includes a unique identifier, name, description, images, and tags, which is meant to describe the business intent and uses cases for an API. Rely on the OpenAPI...
The description of each API should be one to three paragraphs at the most, covering the business details of what an API delivers. Keep the technical details part of the OpenAPI info description, an...
API Operation Descriptions is one of those areas of how descriptions are used across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but t...
API Operation Descriptions is one of those areas of how descriptions are used across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but t...
The unique identifier for an API is usually just a slugified version of the name of the API, if the name conforms to some standard. The purpose of the API identifier, or simply aid, is to provide a...
API-first means prioritizing your APIs as a foundational element, rather than focusing on a specific application, because your APIs can be utilized across a wide range of platformsdesktop, web, mo...
API contracts represent a shared machine-readable understanding of the business and technical requirements established between the producer and consumers of programmatic interfaces used across desk...
APIs is one of those areas of API governance practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people reali...
APIs.json Descriptions is one of those areas of how descriptions are used across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the d...
APIs.json identifiers are a standardized format for allowing API producers to establish a unique identifier for each API contract they provide using APIs.json, which will then be prepended to each ...
APIs.json Images is one of those areas of images and visual identity for APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more...
APIs.json Names is one of those areas of naming conventions across API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter ...
APIs.json Tags is one of those areas of organizing APIs by bounded context and domain that I find myself coming back to again and again. It seems straightforward on the surface, but the details mat...
About is one of those areas of organizing APIs by bounded context and domain that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more ...
Accountability is one of those areas of CI/CD pipelines for API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
In August 2006, shortly after Amazon launched its new cloud storage service Amazon S3, the company followed with a new cloud computing service called Amazon EC2, or Elastic Compute Cloud. Amazon EC...
Applications is one of those areas of API rate limiting approaches that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most ...
Architects is one of those areas of the roles people play in API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
Artificial Intelligence is one of those areas of the types of applications that consume APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the deta...
Artificial intelligence isn’t new, but today’s large and small language models derive their knowledge from various data sources, including vector databases and APIs. These models not only use APIs ...
Providing an overview of the authentication used for an API, with details of how API consumers can obtain the tokens and keys they need has become a common building block in the portals of leading ...
Automation is one of those areas of CI/CD pipelines for API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
The key reason for utilizing APIs is to enable automation of your digital resources and capabilities. By connecting APIs to every digital asset, you’re setting the foundation for streamlined operat...
Availability is one of those areas of API testing approaches that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people...
Basic Auth is one of those areas of how APIs handle authentication that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most ...
An Atom or RSS feed for your blog is still important despite the untimely demise of Google Reader. Twitter replaced a lot of RSS feeds, but the evolution of Twitter has made it clear that we should...
The Blue Button is a platform that allows patients to access, view, and download their personal health records online. Multiple Federal agencies, including the Departments of Defense, Health and Hu...
Blueprints is one of those areas of learning and education around APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
Blueprints is one of those areas of API platform strategy that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people re...
API Evangelist uses the API OAS checker from the Italian government as the validator for all API contracts. I publish an instance dedicated to the APIs.json for any API I am reviewing, providing a ...
Capabilities is one of those areas of how APIs drive digital transformation that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
Capabilities is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most p...
Categories is one of those areas of foundational API knowledge that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peop...
Centralization is one of those areas of API gateway patterns and configuration that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter mor...
Certification is one of those areas of API contracts and their components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more tha...
Certifications is one of those areas of API review processes and practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
The APIs.json created date reflects the first day when an APIs.json contract has been established to define the relationship between API producer and consumers. The created date provides a clear li...
The APIs.json modified date property should be updated to the current date and time anytime a property of the contract is changed. The modified date should demonstrate the short-term freshness of t...
A change log for an API is a proven way for communicating change between API producer and consumer. A change log doesn’t have to robust, just a date, title, and description of what changed, with a ...
Communicating changes to APIs and the operations around them is essential to the delivery of reliable, useful, and secure digital API resources and capabilities. Change is an inevitable aspect of A...
A road map is essential for managing the change of any individual API. A road map communicates change with API consumers, but it also just grounds API producers regarding what is planned for the fu...
Communicating the versioning strategy behind APIs is a useful way to align both API producers and consumers when it comes to API change. Versioning is all about managing and communicating change, a...
Change Log is one of those areas of tracking the history and evolution of APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter mor...
Providing software development kits (SDKs) in multiple of the leading programming languages is a common aspect of operating modern APIs. It is increasingly common to generate SDKs using the OpenAPI...
Code of Conduct is one of those areas of the legal aspects of API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more ...
A Postman Collections is a machine-readable, exportable, and forkable collection of API requests. Postman Collections can be generated from an OpenAPI, running a web application in Chrome using the...
Command Line Interface (CLI) is one of those areas of API development workspaces that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
Communication is one of those areas of the process of deprecating APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
Communities is one of those areas of API ownership models and structures that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
This ties into the rationale behind having an API strategy. An effective API strategy allows you to innovate faster and stay ahead of your competition. The standards and practices you adopt will re...
Compliance is one of those areas of the legal aspects of API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
Consumer 1st-Party is one of those areas of the different types of API consumers that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
Consumer 3rd-Party is one of those areas of the different types of API consumers that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
The description of an API contract should provide one to three paragraphs at the most about why an API contract exists, the nature of the relationship between producer and consumer, and what the bu...
Each API contract should posses a single image that symbolizes the purpose and intent of the API contract, as well as the interested parties involved in the creation of an API contract, or possibly...
The metadata for a contract includes a unique identifier, name, description, images, and tags, which is meant to define the contents and purpose of the API contract, leaving individual APIs and Ope...
The name of an API contract should describe the business intent of the API represented within an API contract, focusing on the needs of the API producer and consumers. Let the APIs.json API name re...
Each API contract should possess one or more tags providing words and phrases that accurately represent the purpose and intent of an API contract. As with other contract metadata, the tags should r...
The APIs.json URL for an API contract provides the source of where a contract originated. This URL helps consumers of a contract access the latest copy of an API contract, and can also help establi...
Each API contract has a unique identifier. This is commonly the root domain or subdomain an API is made available in, however when applied internally this could have it’s own structure based upon i...
The primary reason organizations are designing and deploying APIs is to make data accessible outside the enterprise from database sources. Currently, many APIs mirror the structure of database tabl...
This is the stage of the API lifecycle where you define the foundation for the business and technical details of your APIs, and where the work will occur to produce and iterate upon the API. The mo...
Definition is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peo...
Application programming interfaces, or simply APIs, are the way that desktop, web, mobile, device, and artificial intelligence share data and other digital resources and capabilities. According to ...
Del.icio.us was a social bookmarking service for storing, sharing, and discovering web bookmarks. It was founded by Joshua Schachter in 2003. Del.icio.us implemented a simple tagging system that al...
The design phase of the API lifecycle is where we start organizing all the business and technical details of an API. The goal is to use JSON Schema, OpenAPI, JSON, and YAML to define as much about ...
The develop stage is where we get to work creating a database, generating or writing backend code, and deploy anything to the development gateway. Source control and all the artifacts produced duri...
Development is one of those areas of API maturity stages and progression that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
Shortly after the launch of mobile applications with the iPhone and Android, developers discovered the benefits of using inexpensive HTTP and JSON APIs in their devices. This led to the integration...
Discussions is one of those areas of API governance policies that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people...
Documentation is one of those areas of the process of deprecating APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
Documentation is one of those areas of API portal components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people...
Documentation is one of those areas of self-service API experiences that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most...
Documentation is the essential building block for any API, and the number one pain point for developers when consuming an API. Documentation is how you translate the surface area of your API resour...
Embeddable is one of those areas of the types of applications that consume APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter mo...
Embeddable buttons, badges, and widgets are a primary motivation for developing APIs. Consider the numerous buttons and widgets from social platforms like Facebook and Twitter that we’ve encountere...
If your business depends on applications, you should also have access to the APIs behind them. Every web, mobile, or other type of application is powered by APIs that provide access to data, conten...
Engagement is one of those areas of API leadership and executive engagement that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
Engineering is one of those areas of the roles people play in API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more ...
Environments is one of those areas of API client tooling and configuration that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
Evangelism is one of those areas of how to make an impact in the API space that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
Experiences is one of those areas of how APIs drive digital transformation that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
XML (Extensible Markup Language) is a flexible, text-based format used for storing, organizing, and exchanging structured data across different systems. Developed by the W3C (World Wide Web Consort...
Federation is one of those areas of API gateway patterns and configuration that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
Federation is one of those areas of how APIs shape the next web that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peo...
Foursquare launched in March 2009 at the SXSW Interactive Festival in Austin, TX. It is a location-based mobile platform that makes cities more engaging to explore. By checking in via a smartphone ...
A getting started page is a common and essential building blocks of modern public API providers. Providing a simple step by step overview of what it takes to get started with an API helps reduce fr...
Getting Started is one of those areas of API portal components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peop...
GitHub is a proprietary developer platform that allows developers to create, store, manage, and share their code. It uses Git to provide distributed version control and Github itself provides acces...
GitHub Actions is one of those areas of CI/CD pipelines for API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more th...
GitHub Actions is the native continuous integration and deployment solution that comes with each GitHub repository. GitHub actions provide another artifact that can be managed for an API contract, ...
A GitHub repository has become the preferred place to manage OpenAPI and other artifacts, and APIs.json contracts just bring more order to this already growing approach to using source control as t...
On June 29th, 2006, Google launched the Google Maps API, allowing developers to integrate Google Maps into their own websites using JavaScript. The API launch occurred just under six months after ...
Governance is one of those areas of CI/CD pipelines for API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
The current definition of API centers around the standardization of the design of primarily HTTP APIs using the OpenAPI schema describing the surface area of an API, and Spectral rules that lint th...
Standards are what power APIs. The foundation of modern HTTP APIs is the same foundation for the web–HTTP 1.1, and now HTTP/3. From there other standards like JSON, YAML, OpenAPI, JSON Schema, OAut...
Government agencies should prioritize APIs because they make vital data resources and capabilities accessible across the organization and, when appropriate, to the public via third-party applicatio...
HTTP/1.0 is the first officially recognized version of the Hypertext Transfer Protocol (HTTP), standardized in 1996 as RFC 1945. It established the foundation for communication on the World Wide We...
HTTP/1.1 is the second major version of the Hypertext Transfer Protocol (HTTP), standardized in 1997 as RFC 2068 and later updated in RFC 2616 in 1999. It addressed many of the limitations of its p...
Industries is one of those areas of reusable API blueprints and patterns that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
Industries is one of those areas of organizing APIs by bounded context and domain that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter ...
One often-overlooked use of APIs by technologists is in automating and integrating with existing infrastructure. This includes foundational tools like GitHub, JIRA, and cloud services such as Azure...
Integrated Development Environment (IDE) is one of those areas of API development workspaces that I find myself coming back to again and again. It seems straightforward on the surface, but the deta...
Interactive is one of those areas of API documentation approaches and tools that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
Interoperability is one of those areas of how APIs shape the next web that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than mo...
JSON (JavaScript Object Notation) is a lightweight, text-based data format used for data interchange between systems. It is easy for humans to read and write, and simple for machines to parse and g...
JSON Schema is one of those areas of API specifications and standards that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than mo...
JWT stands for JSON Web Token. It is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is d...
Nobody reads the docs. In my experience about 15% of the people who work with APIs actually read the documentation, with another 35% of them scanning the documentation, and the rest never quite che...
Leadership is one of those areas of the roles people play in API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
Leadership is one of those areas of API stakeholder engagement that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peop...
Leadership will only care about APIs if the outcome aligns directly with their priorities. At the top of that list is generating new revenue. APIs enable the delivery of new products and features, ...
Media Types is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most pe...
Web APIs were in use for websites and automation long before the advent of mobile phones. However, with the introduction of the iPhone and later Android, simple HTTP APIs became essential for deliv...
Mock Servers is one of those areas of API mocking and virtualization that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than mos...
Monitoring the performance of APIs is a common part of operating internal and external APIs. Select operations within an API can have simple latency tests, as well as more robust load and network t...
Every API should have an uptime monitor to track the status of the API. The bounded context of the API being monitored, which operations you monitor, how often you monitor the uptime of an API will...
OAuth 2.0 is an authorization framework that allows third-party applications to securely access a user’s resources without requiring the user to share their credentials. Instead, it uses access tok...
APIs make the digital resources and capabilities across your applications visible and easily accessible. Imagine running a business without being able to see your supply chain, factory floor, or di...
On-Premise is one of those areas of API integration patterns that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people...
On-Premise is one of those areas of API solution delivery models that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most pe...
Onboarding is one of those areas of API portal components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people re...
Onboarding is one of those areas of self-service API experiences that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most pe...
Open Source is one of those areas of API solution delivery models that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most p...
The OpenAPI specification is the technical contract for your HTTP APIs and Webhooks. OpenAPI defines the details of the surface area for your APIs that use HTTP as a transport. It allows you to be ...
HTTP headers are essential to the transport of APIs, and the OpenAPI specification provides a central components storage for HTTP headers, which can then be referenced across API requests and respo...
The OpenAPI components is designed for the centralization of the common elements used across APIs, providing a reusable components library of schema, parameters, security schemes, examples, and oth...
The external docs property for the OpenAPI specification provides an opportunity to ensure the supporting landing page, documentation, or other relevant links travel with the technical contract for...
The info contact object provides you with the ability to define a person, team, or other type of contact as name, email, and URL. The contact information should reflect the overall support strategy...
The info description for each of your APIs should be one to three paragraphs long and tell the technical narrative of your API resources and capabilities. Don’t repeat things already declared in ot...
The info object for the OpenAPI specification provides you with the ability to document the name, identifier, and URL for the license of your API. This is often published as a common code license s...
The info object for the OpenAPI specification allows you to easily define a URL for the terms of service of an API. Ideally this is the terms of service that are specific to the API, and not just t...
The name of your API matters. Hopefully at this point you have crafted a name for your API that reflects your business goals, and you are just copying and pasting the name here in your OpenAPI defi...
The info object for the OpenAPI specification provides the ability to define a date-based or Semantic Versioning for the technical contract for an API. This version is often synonymous with the ver...
The description for each individual API operation should be one or two paragraphs that articulate what is happening when you request the operation, leaving the other parameters, request bodies, res...
OpenAPI operation identifiers push for unique identifiers to exist for any operation present in a single OpenAPI, and is something that can be made unique across an enterprise or industry with the ...
The description you provide for your API parameters show up in documentation, tooltips, intellisense, and other layers of the API lifecycle. Parameter descriptions should really be a single paragra...
When defining HTTP API parameters it is helpful to provide enumerated values when possible. Be as explicit as you can regarding the options that are available to API consumers. Parameter enums help...
The OpenAPI operation parameter in property allows you to designate whether a parameter is used in the path, via query, or is a header. These are the three distinct dimensions for configuration of ...
The names of API parameters represent all of the logical knobs and levers that API consumers can pull on when making requests to APIs. The names should augment and enrich the paths, methods, summar...
Each HTTP API parameter should have a schema associated with it. Most parameters should be string, number, or some other standard data type, but there will be outliers when it comes parameter schem...
OpenAPI provides a rich way to define the types of parameters you are using across your API operations, leveraging JSON Schema to define and validate your parameter types. String, numbers, dates, a...
Each operation can come with an assortment of path, query, and header parameters, depending on how the HTTP protocol is being used as a transport, and an API has been designed. The OpenAPI specific...
GET and DELETE API methods MUST never had request bodies, but POST, PUT, and PATCH quite often have request bodies. Request bodies for APIs should follow the HTTP standard in this way, but should a...
As with any other schema you should provide examples for any request bodies used for your POST, PUT, and PATCH requests. You should work to use the OpenAPI plural examples property, providing intui...
Request bodies can be of multiple IANA media types, with application/json being the most common media type used across modern web APIs. However, form, PDF, XML, and other media types are common pla...
The request bodies for POST, PUT, or PATCH API requests must always have a schema defined using JSON Schema. There are some situations with binary and other formats where this isn’t possible, but t...
2xx series HTTP status codes will vary for API responses depending on the HTTP method applied. It is likely your GET response status code will be 200, but for POST you will have 201, and for PUT an...
Success HTTP API responses should always posses multiple examples of what an API consumer can expect to see returned. Response examples are used in API documentation, mock servers, testing, and man...
Successful HTTP API responses can return any media type, but the most common for modern HTTP APIs is application/json. For older APIs you may see XML, and depending on the resources and capabilitie...
Every successful HTTP API response should possess a JSON Schema reference that defines and allows for the validation of responses, except for when updating with a PUT, or deleting with a DELETE, an...
4xx series HTTP status codes help us deal with the API consumer error that is inevitable across API consumption. These status code let applications and integrations know when they have made a mista...
4xx should employ a standardized schema as part of the response, ideally something like Problem Details for HTTP APIs, expressed as OpenAPI and JSON Schema. 4xx should provide API consumers with wh...
5xx HTTP status codes for responses help standardize how API producers communicate that an error has occurred via a backend system responsible for for returning data used in an API response. 5xx se...
Each individual API operation should possess a security definition property that is in alignment with the security schemes applied across an collection of APIs as defined by OpenAPI, but also the w...
The operation summary for an API is the first chance you have to describe the purpose of a single API operation in as few words as possible–don’t waste words, make them all count. Make your summari...
Tags applied to API operations help organize and group paths, methods, and operations in documentation, but also shape the bounded context of APIs for generating SDKs, sandboxes, testing, security,...
The paths for your API as defined by OpenAPI are how you guide your consumers into your wholesale outlets to purchase all of your digital resources and capabilities. These paths are baked into desk...
Schema defined as part of OpenAPIs should possess a description of the object in its entirety. Let each property description tell more about the parts of an object and work to describe object in re...
The names of schema, like other naming should be consistent, and adequately describe what a digital object is. Schema names should follow a consistent schema casing, length, and approach across all...
Schema properties allow you to describe the individual properties of the digital objects you pass back and forth as part of each API request and response, describing the name, type, shape, patterns...
Schema property descriptions should be single paragraph narratives about what a schema property represents as one part of an overall digital object being passed to an API or returned from an API. S...
The names of schema properties should be plain language, follow a consistency structure and casing. These properties should all work in concert to deliver a useful digital representation as needed ...
The overall shape of the objects we send along with each API request or receive back as part of API responses will impact much more than just how data is used in applications, and will define quali...
OpenAPI provides us with the ability to ensure that all schema used across APIs are of a common type, utilizing objects, arrays, string, numbers, dates, and other common data types as expressed by ...
Schema types are the foundation of the digital objects being passed back and forth via the web for use in desktop, web, mobile, device, and artificial intelligence applications. Schema types single...
The OpenAPI specification provides the ability to centrally define how we use API key, JWT, or OAuth authentication across our APIs. The OpenAPI security schemes property centrally defines what aut...
Each OpenAPI has a central tags object that allows you to tag the technical contract of an API, with tags applied across each of the API operations defined by the OpenAPI. These tags get used to ca...
Using the latest version of the OpenAPI specification is always where you want to be when it comes to defining the surface area of your HTTP APIs and Webhooks. The latest, 3.1.0, as of this writing...
Operations is one of those areas of API governance practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people...
Operations is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peo...
Organization is one of those areas of API governance practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peop...
Organizations is one of those areas of organizing APIs by bounded context and domain that I find myself coming back to again and again. It seems straightforward on the surface, but the details matt...
Organizations is one of those areas of source control for API artifacts that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
Standards are essential to API operations and API governance. Internet, industry, and enterprise standards should be the defining quality of API operations. APIs begin with HTTP, then layer on JSON...
API Evangelist uses the API OAS checker from the Italian government as the validator for all API contracts. Right now it is just a stripped down static publishing of each API w/ the operational and...
Performance is one of those areas of API testing approaches that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people ...
A plans page outlining each of the access tiers for an API, provides a one-stop for business and technical API consumers to learn about how to onboard with an API, what features they get, the rate ...
Platform Development Kits (PDK) is one of those areas of code artifacts around API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the det...
API and developer portals have become a common wholesale outlet for enterprises to make API resources and capabilities available to an internal, partner, or public consumer audience. Most leading t...
Postman Collections provide another type of technical contract for your API, but one that is designed for execution, testing, and automation. The Postman Collection format is a format developed by ...
Privacy Policy is one of those areas of the legal aspects of API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more t...
HTTP status are often not sufficient in conveying enough information about API errors. Humans behind Web browsers can be informed about the nature of a problem, non-human consumers of HTTP will not...
Producer 1st-Party is one of those areas of the different types of API producers that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
Producer 3rd-Party is one of those areas of the different types of API producers that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter m...
Producer Internal is one of those areas of the different types of API producers that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter mo...
Product-led is an API industry phrase for describing that you are developing your APIs as products rather than just technical details of applications. Leading with a product mindset means that you ...
Product-Led is one of those areas of what makes API programs succeed that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than mos...
Production is where an API is now open for business. This is where documentation, SDKs, plans, terms of service, privacy policies, and other elements are in place. This is where blog posts, videos,...
Production is one of those areas of API maturity stages and progression that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
Properties is one of those areas of API contracts and their components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
Provenance is one of those areas of what makes API programs succeed that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most...
Rate Limiting is one of those areas of API security practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peopl...
RSS (Really Simple Syndication) and Atom are web feed formats used to syndicate and distribute content from websites, enabling users to stay updated with the latest posts, news, or media without vi...
Regulation is one of those areas of industry-specific API considerations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
Reinventing the Wheel is one of those areas of foundational API knowledge that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more tha...
Repeatable is one of those areas of CI/CD pipelines for API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
Repositories is one of those areas of source control for API artifacts that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than m...
REST APIs (Representational State Transfer Application Programming Interfaces) are a standardized approach to building web services that allow systems to communicate over the HTTP protocol. Based o...
Request Bodies is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most...
February 7th, 2000, Salesforce.com officially launched at the IDG Demo 2000 conference. Salesforce.com launched its enterprise-class, web-based, sales force automation as a “Internet as a service”....
Guidance must be self-service and something stakeholders in API operations should have access to in their own time and space. Just-in-Time API Guidance ™ is kept as simple YAML and Markdown which c...
Service Level Agreement (SLA) is one of those areas of the legal aspects of API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the detail...
SOAP (Simple Object Access Protocol) is a messaging protocol used for exchanging structured information in web services over a network. Developed by Microsoft in the late 1990s, it became a standar...
The Slack API, which allows developers to build custom integrations and applications for the Slack platform, was developed alongside Slack itself. Originally designed as an internal communication t...
Source Control is one of those areas of tracking the history and evolution of APIs that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter...
Sovereignty is one of those areas of how APIs shape the next web that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most pe...
Sovereignty is one of those areas of regional API deployment strategies that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
Both Microsoft Excel and Google Sheets have the capability to call external HTTP APIs, allowing you to retrieve data, algorithms, and other resources essential for your spreadsheet’s orchestration,...
The staging stage of the API lifecycle is where we harden the deployment of an API, testing the contract, performance, and security of each API. This stage should have a supporting gateway that API...
Status Codes is one of those areas of REST and RESTful API design that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most p...
Support is a required part of operating any API, ensuring that API consumer have at least one, if not multiple self-service and direct support channels to take advantage of when they have questions...
Swagger was an open-source framework originally developed by Tony Tam at Wordnik to design, build, document, and test RESTful APIs. It provided a standardized way to describe API endpoints, methods...
Having the teams defined behind each API helps ensure that both product and engineering stakeholders can be contact, and informed as part of producing and consuming APIs. The team structure for ent...
It may seem obvious to tell technical professionals they need to care about APIs, but it’s not just about understanding HTTP protocols and technical details. They should also grasp how APIs fit int...
API Evangelist uses the API OAS checker from the Italian government as the validator for all API contracts. I publish an instance dedicated to the OpenAPI for any API I am reviewing, providing a go...
Terms of Service (TOS) is one of those areas of the legal aspects of API operations that I find myself coming back to again and again. It seems straightforward on the surface, but the details matte...
Transformations is one of those areas of API gateway patterns and configuration that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter mo...
In 2007, Twilio launched as a groundbreaking API-as-a-product platform, introducing a voice API that enabled developers to make and receive phone calls through any cloud application. Over the next ...
How API consumers are applying and integrating your API resources and capabilities will help you define where you invest across the API lifecycle. Knowing how your API consumers will integrate, aut...
Uses cases provide a simple way to align the design, development, and delivery of APIs with business interests, but most importantly customer use cases. Use cases are about pausing and putting some...
Defining what the target uses cases are for an API, while also regularly evaluating how existing consumers are using an API, is how you tighten the direction of an API. The what portion of uses cas...
The place to start with defining any API is properly defining who the target audience is. Ideally the who is a person or group of people, defined as real-world teams or customers, or more generaliz...
Having an awareness of why your API consumers will be applying your digital resources and integrating capabilities into their systems helps you ground your road map. Being honest about the incentiv...
Validation is one of those areas of API testing approaches that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most people r...
Validations is one of those areas of API review processes and practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than ...
Verification is one of those areas of API contracts and their components that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
Visibility is one of those areas of reusable API blueprints and patterns that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than...
Visibility is one of those areas of what makes API programs succeed that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most...
Early web applications relied on static HTML to present information on the web. As these applications evolved, they became more dynamic, initially pulling data from a single backend database. Howev...
A GitHub organization, either in the cloud or on-premise, provide an excellent way to organize and direct all the work occurring across a domain within an enterprise. GitHub organizations are desig...
Postman Workspaces provides a collaborative way to organize the defining, design, development, and operation of an API, offering a way for both API producers, consumers, and other business or engin...
XML-RPC is a protocol that enables remote procedure calls (RPC) using XML-encoded messages transmitted over HTTP. Introduced in the late 1990s, it allows systems to execute functions on a remote se...
authentication is one of those areas of API security practices that I find myself coming back to again and again. It seems straightforward on the surface, but the details matter more than most peop...
