The course link: https://app.pluralsight.com/library/courses/designing-restful-web-apis
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
3- Cachable
4- Uniform Interface
5- Layered system
REST API’s have some parts
+ Request: Verb + URI + Request Body
+ Response: Status Code + Headers +Response Body
![](http://yakupbugra.com/wp-content/uploads/2020/08/image-9-1024x562.png)
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:
/api/customers/123/invoices
/api/invoices/2020-08-14/payments
/api/games/halo-3/ratings
- Lists return same shapes:
/api/invoices
/api/customer/123/invoices
- 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
![](http://yakupbugra.com/wp-content/uploads/2020/08/image-8.png)
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.