Everything You Need to Know About OpenAPI
tl;dr: API design is important, yet it is only useful if it's well-documented and consistently represented across every API surface area (docs, SDKs, etc.). OpenAPI gives you greater visibility into your API, enabling you to unify all aspects of errors, responses, and parameters, ensuring consistency. This open-source documentation project will help you understand the OpenAPI Specification.featured in #541
Everything You Need to Know About OpenAPI
tl;dr: API design is important, yet it is only useful if it's well-documented and consistently represented across every API surface area (docs, SDKs, etc.). OpenAPI gives you greater visibility into your API, enabling you to unify all aspects of errors, responses, and parameters, ensuring consistency. This open-source documentation project will help you understand the OpenAPI Specification.featured in #537
How To (And How Not To) Design REST APIs
- Jeff Schnitzer tl;dr: "In my career, I have consumed hundreds of REST APIs and produced dozens. Since I often see the same mistakes repeated in API design, I thought it might be nice to write down a set of best practices. And poke fun at a couple widely-used APIs. Much of this may be "duh", but there might be a few rules you haven't considered yet."featured in #537
How To (And How Not To) Design REST APIs
- Jeff Schnitzer tl;dr: "In my career, I have consumed hundreds of REST APIs and produced dozens. Since I often see the same mistakes repeated in API design, I thought it might be nice to write down a set of best practices. And poke fun at a couple widely-used APIs. Much of this may be "duh", but there might be a few rules you haven't considered yet."featured in #536
Common Design Patterns At Stripe
- Paul Asjes tl;dr: “You might disagree with how the Stripe API is designed, and the design you end up with is likely going to be different than what we use. That’s just fine, since different companies have different use cases. Instead I present here some design patterns that I believe are generic enough to be useful for just about anyone in the API design process.”featured in #526
Common Design Patterns At Stripe
- Paul Asjes tl;dr: “You might disagree with how the Stripe API is designed, and the design you end up with is likely going to be different than what we use. That’s just fine, since different companies have different use cases. Instead I present here some design patterns that I believe are generic enough to be useful for just about anyone in the API design process.”featured in #525
How I Learned To Stop Writing Brittle Tests And Love Expressive APIs
- Titus Winters tl;dr: “Expressive test APIs are a powerful tool in the fight against brittle, implementation-detail heavy tests. A test written with IsSquare(output) is more expressive (and less brittle) than a test written with details such as JsonEquals(.width = 42, .length = 42), in cases where the size of the square is irrelevant.”featured in #507
Designing APIs For Humans: Error Messages
- Paul Asjes tl;dr: A valuable error message should: (1) Use the correct HTTP status code. (2) Wrap the error in an “error” object. (3) Be helpful by providing the error code. (4) The error type. (5) A link to the relevant docs. (6) The API version used in this request. (7) A suggestion on how to fix the issue. Paul shares an example by Stripe.featured in #499
In-Depth: OpenAPI Client Generation Comparison
- Sagar Batchu tl;dr: OSS SDK generators might seem free, but they have a lot of hidden costs that any enterprise user should consider carefully. Plenty of bugs, no support, spotty OpenAPI compatibility, and more will require a serious investment of engineering resources. Read on to learn about the business and technical considerations and explore available options.featured in #492
Data-Caching Techniques For 1.2 Billion Daily API Requests
- Guillermo Pérez tl;dr: The cache needs to achieve three things: (1) Low latency: It needs to be fast. If a cache server has issues, you can’t retry. (2) Up and warm: It needs to hold the majority of the critical data. If you lose it, it would surely bring down the backend systems with too much load. (3) Consistency: It should never hold stale or incorrect data. “A lot of the techniques mentioned in this article are supported by our open source meta-memcache cache client.”featured in #486