Downloaded 19 times
Uploaded byVictor Osimitz
Intro to API Design Principles
An API is an interface that allows software components to interact and abstracts away complexity. When designing a system, getting the interfaces right is important. RESTful APIs follow principles like being stateless and using standard HTTP actions and errors to organize resources in a discoverable and uniform manner. APIs should focus on the data model and use standards like JSON and HTTP verbs, while pragmatically modifying REST principles only to ease the consumer's experience.
Intro to API Design Principles
- 1. API Design Principles Victor Osimitz Slice Technologies
- 2. What is anAPI? • An API is a channel over which distinct software components interact with each other • A good API is a clean façade in front of the underlying implementation – Abstracts away complexity and messiness – Decouples clients from the service – Allows for flexibility in the underlying service • API: Application Programming Interface
- 3. The Power ofan Interface Implementations Interface • Completely different implementations, but a consistent, familiar interface. • What if we change the interface? • Drive on the opposite side of the road? • Manual transmission? When designing a system, get the interfaces right, even if you get everything else wrong.
- 4. Typical Client-Server Architecture • Data models vary wildly • Multiple servers behind a load balancer • Basic data operations: retrievals, adds, edits, deletes • Fairly small set of errors • May or may not require authentication
- 5. Principles of RESTfulAPIs •Representational State Transfer •Based on HTTP, which powers much of the Internet REST •REST APIs are organized around data rather than actions • Slice resources represent the data for a particular user: orders, items, etc Resources •Since requests will hit different servers, each request stands alone Stateless • Standard HTTP actions and errors •GET, PUT, POST, DELETE with standard meanings Uniform •The entire data model should be accessible from only a few specified entry points •Reduced dependency on documentation Discoverable
- 6. A Few Standards • JSON: flexible, lightweight data format (some XML) • Instance: a resource representing a specific object, e.g. “order 123” • Collection: a resource representing a group of objects, e.g. “all orders” • HTTP Verbs – GET: retrievals – PUT/POST: full-object write – DELETE: deletions – PATCH: overwrite a field • Standard HTTP codes: – 200: we’re cool – 300: ask that guy over there (redirect) – 400: you screwed up (request error) – 500: we screwed up (server error)
- 7. Pragmatic REST Makereasonable modifications when they make life easier for the API consumer, otherwise stick to REST principles.
- 8. Takeaways 1. Interfacesmatter. 2. In your API, focus your energy on the data model. Use standards for everything else. 3. Break the rules if and only if it makes life easier for the API consumer.