Proper API Design Allows for:
- Platform Independance
- API and the Client should have an agreedupon method of communicating
- Service Evolution
- new features can be added without breaking any existing functionality
- these new features should be discoverable
REST - Representational State Transfer
RESTful API's Principles (using HTTP):
- REST APIs are designed around resources (objects, data, or services) that can be accessed by a client
- Each resource as an identifier that identifies it
- this is a URI (Uniform Resource Identifier)
https://my-fake-api.com/example/URIs- URIs should be based on nouns (the resource) and not verbs (operations on the resource) (above is a good example)
- adopt consistent naming conventions
- use collections and hierarchy
- provide navigable links to associated resources
- keep URIs simple
- Avoid chatty APIs which are APIs that send numorous small requests
HTTP Common Verbs:
- GET - retrieves a representation of resource at given URI, message body contains details of resource
- returns 200 OK, or 404 (Not Found) if resource can't be found
- POST - creates a new resources at a given URI, message body contains details of new resource, can also be used to trigger operations that don't generate a new resource
- returns 200 , no result to return 204, invalid data 400
- PUT - creates OR replaces a resource at a given URI, body of request specifies targeted resource
- new resource returns code 201
- updated resource returns code 200 OK, 204 NO Content, or 490 Conflict
- PATCH - partial update of resource
- DELETE - removes resource at a given URI
- sucessful delete returns 204 No Content or 404 if it didn't exisit
- API structure/building