hateoas, HATEOAS, an abbreviation for Hypermedia As The Engine Of Application State, is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in some service-oriented architectures (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).
put for Create, identifier is knows by the client.
put for update, existingId, full replacement.
put is idempotent, produce the same result regardless if that's called one time or hundred times. Because of that, it cannot be used for partial udpate, requires to send all the properties.
post as create, create on a parent resource
post as update, on instance resource - can be used for partial update.
post, only method not idempotent.
GET, PUT DELETE, HEAD are idempotent, invoke multiple times, should get the same result.
rest client vs browser
versioning
version in URL vs media type
hypermedia is paramount
linking is fundamental for scalability - not for performance, but the ability for other systems to interact, allow system to grow over time.
pagination
- offset
- limit
errors
- as descriptive as possible
- as much information as possible
- developers are your customers
security
- avoid sessions when possible
-- authenticate every request if necessary
-- stateless
- authorize based on resource content. NOT URL!
- Use existing protocol
-- oauth 1.0a, oauth2(begin with SSL, then translate to bear token), basic over SSL only
- custom authentication scheme
-- only if you provide client code/SDK
-- only if you really, really what you're doing
- use api keys instead of Username/Passwords
401 vs 403
- 401 "unauthorized" really means Unauthenticated
- 403 "forbidden" really means Unauthorized
api keys
- entropy
- password reset
- independence
- speed
- limited exposure
- traceability
- ids should be opaque
- should be globally unique
- avoid sequential numbers (contention, fusking)
- good candidates: UUIDs, 'Url64'
Maintaince
- use HTTP redirects
- create abstraction layer/endpoints when migrating
- use well defined custom Media Types
REST+JSON API Design - Best Practices for Developers
