Skip to content

Designing Restful API (Study Notes)

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

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

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.