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/
New blog post: Designing for Short Completion Menus
Code completion is how developers explore your API. Fewer, more focused options lead to better usability. A look at fluent API design using RestTemplate vs RestClient.
https://poutsma-principles.com/blog/2025/05/15/designing-for-short-completion-menus/
Goedemorgen! 
Hebben jullie onze documentatie over API's al eens gebruikt?
Onze handleiding "Bouw een API" vertelt je over hoe je op basis van een OpenAPI Specification (OAS) een API bouwt. Het voordeel hiervan is dat je niet direct hoeft te coderen, maar dat je wel al omschrijft hoe de API er uit moet komen te zien.
https://developer.overheid.nl/kennisbank/apis/aan-de-slag/bouw-een-api
Mochten jullie feedback op het artikel hebben, een pull request/ issue inschieten mag altijd 
APIs Over IPAs 17: Aligning API Design to Business Outcomes with James Higginbotham, LaunchAny https://buff.ly/RIMPEex
"In this episode, Derric Gilling chats with James Higginbotham, founder of LaunchAny, about designing successful API strategies that drive business value. "
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/
Hoe staat het ervoor met de API Design Rules van de Nederlandse overheid? Tim van der Lippe van @Logius schreef als beheerder van de standaard een blogpost met de nieuwste inzichten en ontwikkelingen.
Werk jij met API’s in het publieke domein? Blijf op de hoogte en lees de update hier 
https://developer.overheid.nl/blog/2025/04/02/update-api-design-rules
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
The Information Architecture Philosophy Behind RESTful Web API Patterns and Practices Cookbook https://buff.ly/97cOvn8
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.
"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
Navigating Type Systems: Closed vs Open Universes in Software Development
In the realm of software development, understanding how to effectively model choices within type systems is crucial. This article delves into the nuances of closed and open universes, exploring their ...
GitHub's Support for OpenDAL: A Seamless Transition to the New Cache Service
In a collaborative effort, GitHub has reached out to OpenDAL to aid in the migration to its new GitHub Actions Cache Service. This partnership highlights the importance of API versioning and user iden...
Now that PHP8.4 support new MyClass()->method() without parentheses does it still make sense to add or have empty named constructor like MyClass::new() or MyClass::make() or MyClass::create()
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
2024 State of the API Report
https://www.postman.com/state-of-api/2024/
"2024 marks the 6th year of the State of the API—the most comprehensive survey on APIs with over 5,600 developers and API professionals sharing their thoughts this year." -- #postmanm
"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/
Mike Amundsen 
