API (Application Programming Interface): A set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.
2000-2010: XML-HTTP, REST, SOAP
2010-2020: GraphQL, gRPC
REST (REpresentational State Transfer): Architectural style for distributed hypermedia systems. There are 5 main principles:
1- Seperation of Client – Server
2- Server requests are Stateless
4- Uniform Interface
5- Layered system
REST API’s have some parts
+ Request: Verb + URI + Request Body
+ Response: Status Code + Headers +Response Body
Nouns are good, verbs are bad. use /customers insted of /getCustomers
GET: Retrieve a resource
POST: Adding/Creating a resource
PUT: Updating an existing resource
PATCH: Update resource with some partial changes
DELETE: Remove an existing resource
Prefer camelCasing on naming request and response bodies.
- For sub-objects and associations, use URI navigation:
- Lists return same shapes:
- Lists should support paging
- Use query strings for paging: /api/sites?page=1&pageSize=25
- Use wrappers to imply paging. You can give some extra information such as totalCount, nextPage and previousPage links in response body or response headers.
Return error object
You cant fix an API after publishing it. Users rely on the API not changing. When requirements change, evolve the API without breaking existing clients.
- Versioning in the URI path is most offered way /api/v2/customers
Cross Domain Security: Don’t allow a separate domain to call API. But, this only limits browser.
Cross Origin Resource Sharing (CORS): Domain, resource and verb control. This only limits browser.
Authentication: Who you are? Determine Identity. Credentials, claims
- Cookies: Easiest and common.
- Basic Auth: Without SSL, its risky
- Token Auth: Most common. Should expire faster than cookies.
- OAuth: Use to allow third parties.
Authorization: What you can do? Roles, rights.