New post: Fluent Internals

Part 4 of Crafting Fluent APIs dives into the type design behind RestClient: self-bounded generics, fluent states, and how the API stays clean on the surface.

https://poutsma-principles.com/blog/2025/06/03/fluent-internals/

API caching can save servers some serious work, cut down on costs, and even help reduce the carbon impact of an API. However, it is often considered an optimization rather than what it truly is: an integral part of API design. #ApiDesign #GreenTech https://apisyouwonthate.com/blog/api-design-basics-cacheability/

"API keys are foundational elements for authentication, but relying solely on them is inherently a risky proposal.

Firstly, there’s the reality that API keys are not securely designed — they were never meant to be used as the sole form of authentication, and as such, they aren’t really built for the task. These keys can often be easily stolen, leaked, or, in some cases (especially if generated incrementally), outright guessed. An API key is suitable for tracking usage but is poor for security.

There is also the additional reality that keys in their default state lack some critical functionality. There’s not a lot of verification built-in for identity management, and what does exist offers very little in the way of granular access control.

Ultimately, solely relying on API keys is a mistake common with novice developers but frighteningly common even in advanced products.

Best Practices
Instead of relying heavily on API keys as a sole mechanism, combine those keys with additional approaches such as OAuth 2.0 or mTLS. Implement rigorous expiration and rotation policies to ensure that keys which are made public are only useful for a short amount of time. Consider more advanced approaches, such as IP whitelisting or device fingerprinting, to add another layer of security atop the API key process."

https://nordicapis.com/9-signs-youre-doing-api-security-wrong/

Spec-First or Code-First? Choosing Your OpenAPI Strategy with Quarkus vs. Spring https://myfear.substack.com/p/spec-first-or-code-first-choosing
#Java #Quarkus #APIDesign #OpenAPI

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

I’m so excited that this book is back on track!

Build APIs You Wont Hate 2: This Time Its Serious

Roughly 80% of the internet is roughly built APIs, held together with enough duct-tape to choke all the hamsters powering it. Let's learn how to build them properly.

#apidesign
#apidevelopment

https://leanpub.com/build-apis-you-wont-hate-2

"Getting to this point isn’t unusual. Clients clearly think they’re making the call correctly, or else they would fix the endpoint themselves. Some misspellings are difficult to catch. The enum USER_RETREIVE may not be noticed from USER_RETRIEVE, especially if picking it from a list. Misspellings happen and they’re not always caught before making it to the contract. As an aside, that’s why it’s important writers routinely check development’s changes. This applies, too, to our testing calls in Postman, where manually entering endpoints and values are more pervasive.

The reason this isn’t caught is simple: We’re not expecting it.

For our testing, the call is made and we get results. We may even spot check some of them. But generally, results aren’t examined that closely. For instance, how often do you so carefully examine a returned list of 50 or 100 items? You check may check that the objects are complete but not that the list conforms to the search criteria.

The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling."

https://robertdelwood.medium.com/understanding-query-parameter-handling-in-rest-calls-1821e0c3fa8c

I’ve written a guide on API Design for Speakeasy which is almost everything I know about designing an API from scratch. Basic theory of everything, pros and cons of various standards, pitfalls to watch out for, and best practices to stick to. Give me feedback and I’ll improve it. What’s missing. What could I add. Not done yet! #ApiDesign https://www.speakeasy.com/api-design

"A handful of root causes are likely behind API drift. One standout point is the simple fact that API documentation is typically incomplete. Only 10% of organizations fully document their APIs, found a 2023 EMA report. Without a strong documentation culture or comprehensive API inventory management, it’s more common to see a disorganized use of service descriptions.

Furthermore, many groups are still early on in their API governance strategies. As the number of APIs increases within a company, those without established standards for maintaining the API lifecycle are more likely to experience incompatibilities or even see services turn into shadow or zombie APIs.

According to Lorna Mitchell, VP of Developer Experience at Redocly, API drift is intrinsically tied to a lack of comprehensive testing. Drift can occur for design-first APIs if there aren’t clear tests of whether what is built actually matches what’s described. This is a problem that can easily become endemic, she says. “Code gets duplicated, and the chasm widens.”"

https://nordicapis.com/understanding-the-root-causes-of-api-drift/

#APIDesign #APIs #APIGovernance #APIDocumentation #DX #DeveloperExperience: "Most enterprises face a widening API portfolio with an increasing number of API design styles and standards. “Almost all organizations are doing this,” says Brian Otten, VP of digital transformation catalysts at Axway. “I recently talked to a large food retailer that wants to see REST APIs alongside event-based resources and GraphQL,” Otten says.

In addition to the patchwork of API styles, most companies use multiple API gateways or management tools simultaneously. “We are at a point where organizations who already have API management solutions are buying API management solutions,” says Mark O’Neill, VP analyst at Gartner. O’Neill notes that in some cases, this is to replace the current platform, but in many situations, it’s cumulative.

In this multi-paradigm world, API governance is emerging as a key element for bridging disparate styles and avoiding the pains of a sprawling technical portfolio. According to API industry experts, governance will require a greater emphasis on documentation, centralizing common patterns across the organization, consolidating tools, and building internal platforms that improve the developer experience."

https://www.infoworld.com/article/3529600/how-do-you-govern-a-sprawling-disparate-api-portfolio.html

This was an absolute beast to write, a complete guide to OpenAPI v3.1!

Use this guide instead of the Swagger.io guide which was stuck on OpenAPI v3.0, and instead of trying to wrap your brain around the specification which isn’t intended to be user documentation.

#OpenAPI #APIDevelopment
#apidesign #APIDocumentation
https://docs.bump.sh/guides/openapi/specification/v3.1/introduction/what-is-openapi/

#WebAPIs #APIs #TypeSpec #APIDesign #APIDocumentation #OpenAPI #DX #DeveloperExperience: "As we navigate the ever-evolving landscape of API design, it’s crucial that we don’t lose sight of the bigger picture. Although tools like TypeSpec offer enticing promises of simplified development and improved developer experience, we must approach them with a critical eye. The allure of code-like constructs should not come at the cost of collaborative, human-centered design principles. OpenAPI, for all its complexities, has made significant strides in democratizing API design and fostering cross-functional collaboration. Let’s not sacrifice all that on the altar of curly braces." https://passo.uno/typespec-openapi-api-design/

#OpenWeb #WebAPIs #APIDesign #W3C #WebDevelopment:"This document contains a set of design principles to be used when designing web platform technologies. These principles have been collected during the Technical Architecture Group’s discussions in reviewing developing specifications, and build upon the Ethical Web Principles [ETHICAL-WEB]. We encourage specification designers to read this document and use it as a resource when making design decisions."

https://www.w3.org/TR/design-principles/