API documentation can be so much more than API documentation. [It] can be the thread connecting all the stages of the API consumer lifecycle. https://notes.brunopedro.com/2024/06/27/20240627230846/

https://noti.st/christosgkoros/62Hs9L/testing-openapi-definitions-for-better-and-consistent-apis Here, I present how we test APIs described with the OpenAPI standard internally at Postman. We will cover the objectives of testing, which include ensuring correct structure, completeness, consistency, uniformity, style, and documentation. Additionally, we will explore the tool used for testing, Spectral, and where testing fits in our software delivery lifecycle. Furthermore, we will discuss the challenges we faced, such as testing the tests, scaling the number of tests, and scaling the number of engineering teams involved, and how we overcame them.

A list of key finding to illustrate the impact of AIP Guidelines in the areas of API consumption and API production: API Production: Increased Requirement Fulfillment: A controlled developer experiment showed that developers using API Improvement Proposals (AIPs) and an API linter achieved a 10% higher requirement fulfillment rate compared to those without any protocols. Feedback Utility: Among developers using the linter tool alongside AIPs, 75% found it beneficial, aiding significantly in refining their API designs.

Challenges in API usability, as highlighted by Scaffidi [18] and [16], include inadequate documentation, insufficient orthogonality, and mismatches between API abstractions and application requirements. https://dl.acm.org/doi/10.1145/3613905.3650803

The role of API Designer can evolve from Product Design or Architecture. API Designers should understand Product, UX, DX, technical and architectural constraints. https://brunopedro.com

When you buy integration tools, you are agreeing to build the actual integration itself. What you are buying is a promise that the integration can be solved more efficiently and more simply than using a general purpose language

An idempotent POST is a concept, useful in payment API scenarios. The API provider wants to ensure that if an API call to make a payment fails during execution – such as in timeout scenarios where no discernable HTTP response is returned to the client – subsequent attempts do not result in a duplicate payment instruction submitted. Idempotency is achieved by requiring the client to submit the same instruction with an identifier that signals to the API provider that they might have seen this instruction before.

APIs are Forever When a social media post graces the internet, it leaves a permanent impression on web users thereafter — that’s to say, it remains visible and “on the record” until the end of days. A similar thing happens with AWS’ APIs, though those outcomes are more intentional. When AWS introduces an API, Vogels believes that this API must remain ever-present and largely unchanged. Once companies fundamentally change or remove a longstanding API from general availability, business customers who’ve built atop it will suffer.

I had a conversation recently involving contract testing between partners. The provider provides the contract during their ci/cd process before the deployment. The consumer will validate it and if something fails, the change is rejected and the deployment never occurs. The concept of consumers signing off and blocking deployments is very interesting as it empowers and handles the control to the consumer.

https://www.voxgig.com/podcast/episode-170-christos-gkoros-repeat-api-designer-at-postman Who said building robust, production grade APIs had to be hard? As we hope for all technology, the creation and design of APIs has only become easier and more accessible over time. This is due in part to today’s wonderful guest, Christos Gkoros, and his work at Postman as an API designer. Christos comes from a software engineering background and he speaks to us about his journey to his current role.

Strengths of JSON Merge Patch: Easy for users to understand and implement. Naturally idempotent Well-defined semantics Robust to versioning Shortcomings of JSON Merge Patch Cumbersome to modify array values

GraphQL has an advantage over simple Web APIs, as it offers some insight into how many users are using each field of your API. Although this insight may not be completely accurate, it can still be useful in estimating the cost of making a breaking change in a specific field. With this information, you can communicate the potential impact of the change more effectively.

What is an API design specification? A collection of patterns (with examples) Rules about how to apply them Tests to automate compliance

https://noti.st/christosgkoros/Agx6Fh/kubernetes-api-highlight-orchestrating-a-flow This presentation explores the power of Kubernetes REST API in managing and orchestrating complex workflows within a Kubernetes cluster. We will dive into a practical use case of provisioning resources, demonstrating how to effectively leverage the Kubernetes REST API for this purpose. The session will include hands-on examples using Postman to interact with the Kubernetes API and making API calls to manage cluster resources. Additionally, we will introduce Postman Flows, a feature within Postman that allows for the orchestration of a sequence of API requests.

From building APIs I was always intrigued by APIs. Initially, I enjoyed building them. APIs of all kinds; functions, objects, Java interfaces, libraries, and of course, Web APIs. There’s something magical about encapsulating complex information and processes into a single interaction. To the business behind them I fell in love with APIs when I recognized their business significance. Giants like AWS, Twilio, and Stripe have leveraged APIs to build robust, scalable businesses.

An important quality of API design is minimalism, also called #orthogonality. This is a quality shared with programming language design as well. Adding new terms or concepts complicates the design. It adds rules, exceptions, and quirks, thus making it harder to learn. An example is the famous “verb in the resource name” dilemma.

Our rule of thumb we settled on in our practice was to do a Google search. If either the abbreviation or acronym for the concept appeared “top of the fold”, we agreed that it was common parlance. Source

Lay out the Context An API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirements Review the security model & performance expectations.

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.