Skip to content

Latest commit

 

History

History
104 lines (83 loc) · 4.62 KB

apis.md

File metadata and controls

104 lines (83 loc) · 4.62 KB
Raw

Building APIs

Content

Principles

Quotes from Automated Style Guides for REST, GraphQL and gRPC blog post by Phil Sturgeon:

Security

  • Ban HTTP Basic entirely
  • Make sure every endpoint has some sort of security (OAuth 2, API Key, but not both)
  • Every response should support application/vnd.api+json (JSON:API) not just plain-old JSON
  • ID's as integers let people crawl your API incredibly easily, switch to UUID

Errors

  • Your 20X response seems to have errors in it, why do you hate your consumers
  • There are no URLs in your errors, how can anyone find out more information about what went wrong
  • Error format should be RFC 7807

Versioning

  • Keep version numbers out of the URL
  • Version numbers in headers please
  • Ban all versioning and demand evolution (prepare for battle)

API versioning

  1. https://apisyouwonthate.com/blog/api-versioning-has-no-right-way
  2. https://medium.com/good-api/api-change-management-2fe5bba32e9b

API first approach

(in general OpenAPI Specification as a contract)

from Understanding the API-First Approach to Building Products by Janet Wagner:

An API-first approach means that for any given development project, your APIs are treated as "first-class citizens".

from Zalando principles:

API First is one of our engineering and architecture principles. In a nutshell API First requires two aspects:

  • define APIs first, before coding its implementation, using a standard specification language
  • get early review feedback from peers and client developers

API design first vs API code first

Golden thoughts from APIs you won't hate blog

from There's No Reason to Write OpenAPI By Hand blog post by Phil Sturgeon:

Some API developers use API descriptions to plan the interface of an API before building it, which is known as the "API design first" workflow. Others build the API then generate (or manually produce) API descriptions later, which is the "code-first" workflow.

from API Design-First vs Code First blog post by Phil Sturgeon:

With API descriptions rising in popularity, the main question I hear folks asking about is "API Design-first" or "code-first". This is a bit of a misleading question because these are not two unique things, there are a few variants.

Code-First, Write Docs "When We Have Time"

Code-First, then Annotate

Design First, Ditch for Code First

Design-First, Evolve with Code

from WeWork’s API Specification Workflow blog post by Phil Sturgeon: workflow

Also check