Important HTTP concepts

HTTP verbs

• OPTIONS: Used to retrieve the supported HTTP methods, headers, and other options for a resource.
• GET: Used to retrieve data from the server.
• HEAD: Similar to GET, but only requests the response’s headers, not the response body.
• POST: Used for creating new resources or submitting data to be processed.
• PUT: Used to update an entire existing resource on the server.
• PATCH: Used to update part of an existing resource on the server.
• DELETE: Used to delete an existing resource on the server.
• TRACE: Used to retrieve a diagnostic trace of a particular resource’s request and response messages. The entire request message is echoed back in the response body.
• CONNECT: Used to establish a network connection to a resource, typically for use with SSL/TLS encrypted tunnels. The server connects to the requested resource and returns a 200 OK status code.

HTTP Headers:

• Host: Specifies the server’s domain name being accessed and is required for HTTP/1.1 requests.
• User-Agent: Identifies the client making the request, typically by including information about the user’s operating system, web browser, and version number
• Server: This header identifies the server software used to handle the request.
• Accept: This header specifies the data formats that the client can handle.
• Content-Type: This header specifies the format of the data being sent.
• Content-Length: This header specifies the size of the data being sent.
• Cookie: This header transmits cookies between the client and server.
• Authorization: This header is used to transmit authentication credentials to the server.
• Location: This header redirects the client to a new URL.
• Cache-Control: The server uses this header to specify how long the client should cache the response.

  So far, headers we covered, everyone is expected to know exists at the least.

• ETag: This header provides a unique identifier for a resource. The client can use it to check if a resource has been modified since the last time it was accessed.
• If-None-Match: The client uses this header to check if a resource has been modified since the last time it was accessed, using the ETag value provided by the server.
• Last-Modified: Specifies the date and time the resource was last modified.
• Expires: Specifies the date and time the message should expire.
• Date: This header provides the date and time the server sent the response.
• Referer: This header identifies the URL of the page that the client came from. It is typically used by servers to track the origin of requests and to provide better analytics.
• Content-Encoding: This header specifies the encoding used to compress the response. It can be used to reduce the size of the response and improve performance.
• X-Forwarded-For: This header is used by proxies and load balancers to identify the original IP address of the client.
• X-Frame-Options: This header prevents clickjacking attacks by specifying whether a page can be displayed in an iframe.
• Strict-Transport-Security: This header enforces HTTPS by specifying that the client should only connect to the server over a secure connection.
• Access-Control-Allow-Origin: This header controls cross-origin resource sharing (CORS) by specifying which origins are allowed to access the resource.
• X-XSS-Protection: This header protects against cross-site scripting (XSS) attacks by enabling browser-based filtering.
• Trailer: Specifies which headers will be present in the message trailer.
• Connection: Specifies whether the connection should be kept alive or closed.
• Upgrade: Specifies which protocol or version should be used for the connection.
• X-RateLimit-Limit and X-RateLimit-Remaining: Used to control access to APIs by limiting the number of requests made over a given period.
• X-Custom-Header: Can be used to provide additional information or control the behaviour of a specific API or service.
• X-Request-ID: Provides a unique identifier for a request, which can be used for logging and troubleshooting.
• X-Forwarded-For: Provides the IP address of the original client, which can be helpful when requests are forwarded through proxies or load balancers.
• Range: This header is used to request a specific range of bytes from a resource and for resuming interrupted downloads or partial content delivery.
• Accept-Language: This HTTP header indicates the natural language and locale that the client prefers

REST (Representational State Transfer) Principles

• Resource-oriented: REST should be resource-oriented, with each resource identified by a unique URI (Uniform Resource Identifier). This allows clients to interact with resources in a standardized and consistent manner.
• Use nouns for resource names: Resource names should be descriptive and use nouns rather than verbs or actions. This can make the API more intuitive and easier to understand.
• Use plural resource names: Resource names should generally be plural, even for singular resources. For example, a resource representing a single user should be named “users” rather than “user”.
• Representations: Resources should be represented in a standard format, such as JSON or XML, that clients can easily understand. Clients should be able to request and receive representations of resources in different formats.
• CRUD operations: RESTful APIs should support the standard CRUD (Create, Read, Update, Delete) operations for resources, using the standard HTTP methods (POST, GET, PUT, DELETE) to implement these operations.
• Idempotence: HTTP methods should be idempotent, meaning that multiple identical requests should have the same effect as a single request. This allows for safe and reliable interaction with resources.
• HATEOAS: Hypermedia As The Engine Of Application State (HATEOAS) is a principle that encourages using hyperlinks to navigate between resources in a RESTful API. This allows clients to dynamically discover and interact with resources without knowing the API’s structure.
• Use HTTP status codes: HTTP status codes should be used to communicate the result of API requests. This can help clients understand the outcome of their requests and help with error handling and debugging.
• Versioning: APIs should be versioned to allow for changes and updates without breaking backward compatibility. Versioning can be implemented using URL paths, query parameters, or headers.
• Security: APIs should be secured using standard authentication and authorization mechanisms, such as OAuth or JSON Web Tokens (JWTs). Access to sensitive resources should be restricted to authorized clients only.
• Use appropriate authorization: Authorization is another important aspect of API security, and it is best practice to use appropriate authorization mechanisms, such as role-based access control (RBAC) or attribute-based access control (ABAC), to ensure that authorized clients have access to only the resources they need.
• Pagination: APIs should support pagination for large collections of resources. This can help reduce the amount of data returned in a single response and improve performance and scalability.
• Documentation: APIs should be well-documented, with clear and concise documentation that describes the API’s resources, methods, parameters, and responses. This can help clients understand how to use the API and reduce confusion and errors.
• Error handling: APIs should have clear and consistent error handling, with standard error formats and messages. Errors should be communicated using HTTP status codes and error response bodies and should be documented in the API documentation.
• Use query parameters for filtering and sorting: Query parameters should be used for filtering and sorting collections of resources. This can make the API more flexible and allow clients to retrieve only the needed data.
• Use hypermedia: Hypermedia, such as links and embedded resources, can provide additional context and navigation within the API. This can make the API more discoverable and intuitive.
• Use HTTP headers for metadata: HTTP headers can provide additional metadata about the API request or response. For example, the Content-Type header can be used to specify the format of the response body.
• Use consistent naming conventions: Naming conventions, such as URL paths, query parameters, and response fields, should be consistent throughout the API. This can make the API more intuitive and easier to use.
• Limit resource nesting: Resource nesting should be limited to two or three levels to avoid creating complex and hard-to-use APIs. Instead, flat resource structures with multiple endpoints can be used.
• Use HTTP verbs correctly: HTTP verbs should be used correctly, following the HTTP specification. For example, GET should be used for retrieving data, POST should be used for creating data, PUT should be used for updating existing data, and DELETE should be used for deleting data.
• Design for scalability: APIs should be designed for scalability to handle large numbers of requests and users. This can include techniques such as load balancing, caching, and sharding.
• Monitor performance: APIs should be monitored for performance and uptime using tools such as monitoring and logging. This can help to identify issues early and improve the overall quality of the API.
• Use content negotiation: Content negotiation selects the most appropriate resource representation based on the client’s preferences. It is best practice to use content negotiation to allow clients to request resources in different formats, such as JSON or XML.
• Use rate limiting: Rate limiting limits the requests a client can make within a certain period. Limiting rates to prevent clients from overwhelming the API and improving performance and reliability is the best practice.
• Provide analytics: Analytics can be used to monitor the performance and usage of the API and identify trends and issues. It is best practice to provide analytics to clients to help them understand how the API is being used and identify improvement opportunities.