HTTP methods

Core HTTP methods & how they map to CRUD

Here’s a breakdown of the main HTTP methods used in RESTful APIs:

GET (Read)

Purpose
To get the current information about a specific item (resource) or a list of items

Safe
Yes, it does not change anything on the server.

Idempotent
Yes, making the same GET request multiple times will always give you the same result/information, and won’t cause any extra changes on the server.

Cacheable
Yes, web browsers and servers can save (cache) the responses to GET requests to make future requests faster.

Common status codes:
– 200 OK: Everything worked, here’s the data.
– 404 Not Found: The resource you asked for doesn’t exist.
– 304 Not Modified: The resource hasn’t changed since your last request, so you can use your cached version.

POST (Create)

Purpose
To send data to the server, usually to create a brand new item (resource) or to trigger some process.

Safe
No, it changes the state of the server (e.g., adds new data).

Idempotent
No, making the same POST request multiple times might create duplicate resources (e.g., submitting the same form twice might create two identical orders).

Cacheable
Only rarely, if the response explicitly says it can be cached.

Common status codes
– 201 Created: The resource was successfully created (and the response usually includes the address of the new resource).
– 400 Bad Request: The data you sent was not valid or complete.
– 409 Conflict: The request could not be completed because of a conflict with the current state of the resource.

PUT (Update/Replace)

Purpose
To completely replace an existing item (resource) at a specific web address (URL), or to create it if it doesn’t already exist at that address.

Safe
No, it changes the resource.

Idempotent
Yes, sending the same PUT request multiple times will have the exact same final effect (the resource will be replaced with the same data each time).

Cacheable
No.

Common status codes
– 200 OK or 204 No Content: The resource was successfully updated.
– 201 Created: The resource was successfully created (if it didn’t exist before).

PATCH (Partial update)

Purpose
To make specific, small changes to only certain parts (fields) of an existing item (resource).

Safe
No, it modifies the resource.

Idempotent
Not guaranteed to be idempotent. While you can design it to be, a repeated PATCH might have different effects depending on the current state of the resource.

Cacheable
Sometimes, if the response includes explicit freshness information.

Common Status Codes

– 204 No Content: The partial update was successful, and there’s no content to return.
– 200 OK: The partial update was successful, and some content was returned.
– 400 Bad Request: The data sent for the partial update was invalid.
– 409 Conflict: The request could not be completed due to a conflict.
– 415 Unsupported Media Type: The format of the data sent for the patch is not supported.

Note: PATCH uses less internet data for small changes compared to PUT (which sends the entire updated resource).

DELETE (Delete)

Purpose
To remove the item (resource) at the specified web address (URL).

Safe
No, it changes the resource by removing it.

Idempotent
Yes, once a resource is deleted, trying to delete it again will have no additional effect (it might just return a “Not Found” message, but no new deletion happens).

Cacheable
No.

Common status codes
– 204 No Content: The resource was successfully deleted, and there’s no content to return.
– 200 OK: The resource was successfully deleted, and some content is returned (e.g., a confirmation message).
– 404 Not Found: The resource you tried to delete was already gone.

Why HTTP methods are important

Using HTTP methods correctly isn’t just a small detail; it’s a core part of how good web APIs are designed and how well they work. Their importance comes from several key reasons:

Standard and predictable

HTTP methods give APIs a language that everyone understands. When APIs stick to the meaning of methods like GET, POST, PUT, and DELETE, they act the same way no matter what app is using them or what technology the server runs on. This makes it much easier for developers to connect to an API, and the results are more predictable.

Actions are clear

Each HTTP method naturally tells you what it’s supposed to do. For example, a GET request immediately tells you it’s asking for data without changing anything on the server. A POST request means you want to create something new. This clear meaning makes API requests easier to read and the API itself easier to understand, without needing tons of extra instructions for every single action.

Helps with speed and efficiency

The specific features of HTTP methods allow for various improvements and make APIs more reliable:

– Caching: Methods like GET and HEAD are “safe” (they don’t change anything on the server) and “idempotent” (doing the same request multiple times has the same effect as doing it once). This means that browsers, proxies, and CDNs can save (cache) the answers to these requests. This makes things much faster by reducing the work your server has to do and cutting down on internet traffic.
– Idempotency: PUT and DELETE methods are also designed to be idempotent. This is very important for reliable communication, as it ensures that if a request fails and you try it again, it won’t accidentally create duplicates or mess up your data.
– Safety: “Safe” methods (mainly GET and HEAD) guarantee that making the request won’t cause any unwanted changes on the server. This lets clients make these requests freely without worrying about accidentally changing data.

Follows REST rules

In REST APIs, HTTP methods are fundamental. They help achieve the goals of REST, such as having standard ways to interact, keeping things simple between requests, and easily managing resources. They provide the way for different apps to talk to resources in an independent and scalable way.

Supporting / less‑common methods

Besides the main GET, POST, PUT, PATCH, and DELETE methods, there are a few other HTTP methods that play important, though less frequent, roles in web communication and APIs:

HEAD

Purpose: This method is exactly like GET, but the server does not send back the actual content (the response body). It only sends the response headers. This saves internet data when you only need information about a resource, not the resource itself.

What it does
– Safe: Yes, it doesn’t change anything on the server.
– Idempotent: Yes, repeating a HEAD request has the same effect.
– Cacheable: Yes, caches can use the headers from a HEAD response to update their information about a resource.

When to use it
– To check if a resource exists (you’ll get a 200 OK or 404 Not Found).
– To read metadata like the size of a file (Content-Length) or when it was last changed (Last-Modified), for example, before deciding to download a large file.
– To check if your cached content is still fresh.
– To see API information like rate limits without downloading the full content.

OPTIONS

Purpose
To find out what communication options (like which HTTP methods) are supported for a specific web address or for the entire server.

What it does
– Safe: Yes, it doesn’t change anything on the server.
– Idempotent: Yes.
– Cacheable: No.

When to use it
– It reveals the Allow header in the response, which lists all the HTTP methods that you can use (e.g., GET, POST, PUT, DELETE).
– It’s crucial for CORS (Cross-Origin Resource Sharing) “preflight” checks: Web browsers send an OPTIONS request before a “real” cross-origin request to ask the server for permission. If the server says “yes” (by sending specific Access-Control-Allow headers), then the browser proceeds with the actual request. This helps ensure secure communication between websites from different domains.
– Ideal for automatically documenting an API or discovering its capabilities.

TRACE

Purpose
This method sends the full request it received back to the client. It’s mainly used for diagnosing problems or testing how requests are handled.

What it does

– Safe: Yes.
– Idempotent: Yes.
– Cacheable: No.

When to use it

– To figure out how a request changes as it passes through different network devices or proxies.

Caution: This method is often disabled because it can have security risks (like allowing “cross-site tracing” attacks).

CONNECT

Purpose
Primarily used to set up a direct connection or “tunnel,” most commonly for HTTPS traffic that needs to go through an HTTP proxy server.

What it does
– Not safe, not idempotent, not cacheable: Once the tunnel is set up, the actual data flowing through it is hidden from the basic HTTP layer.

When to use it
In situations where clients need to create a direct TCP connection through a proxy server to a final destination (e.g., when a web browser accesses an HTTPS website through a corporate proxy).

Why these matter for APIs

– HEAD is efficient and lightweight. It allows clients to get information about a resource, validate their cached data, check rate limits, and perform system health checks without having to download the full content.
– OPTIONS helps APIs be “self-documenting” by telling clients what actions are allowed. It’s also essential for enabling secure communication between different websites through CORS.
– TRACE and CONNECT are used for specialised tasks related to network infrastructure, diagnostics, and proxy layers. They are generally not used directly for common operations like getting or changing API resources.

Best practices and considerations

Following these best practices when designing and building APIs with HTTP methods ensures that your API is clear, secure, and easy to maintain over time.

Stick strictly to method meanings
Always use each HTTP method for what it’s truly meant to do. For example, never use a POST request to just get data, and never use a GET request to delete something. Breaking these rules can cause unexpected problems, prevent caching from working, and confuse developers who are trying to use your API.

Handle idempotency correctly for PUT/DELETE
Since PUT and DELETE methods are designed to be “idempotent” (meaning performing the same action multiple times has the same outcome as doing it once), your server must handle this correctly.

– For PUT, if you send the same request several times, the resource should always end up in the exact same final state.
– For DELETE, if you try to delete something that’s already gone, you should still send a success code (like 204 No Content) or a “not found” status (404 Not Found), showing that the resource is no longer there, instead of an error.

Use the right status codes for responses
Always send back the correct HTTP status codes in your API responses.

– 200 OK: For successful GET and PUT operations.
– 201 Created: For successful POST operations (often include a Location header pointing to the new resource).
– 204 No Content: For successful DELETE operations when there’s nothing else to send back in the response.
– 400 Bad Request: When the information sent by the client is invalid.
– 401 Unauthorized or 403 Forbidden: For problems with logging in or not having the right permissions.
– 404 Not Found: When the specific item you asked for doesn’t exist.
– 500 Internal Server Error: For problems that happened on your server’s side. Using correct status codes is vital for effective error handling and for the client’s program to know what to do next.

Security considerations (Authentication/Authorisation)
HTTP methods tell you what action to take, but they don’t make your API secure by themselves. You must put strong security measures in place (like checking who the user is and what they are allowed to do) to ensure that only proper and authorised clients can perform certain actions. For example, a user might be able to GET public data, but they would need specific permissions to POST new data or DELETE existing items.

Sportmonks & HTTP methods in practice

Sportmonks provides a robust GET REST API (e.g., our Football API v3.0) where every endpoint aligns clearly with the HTTP method semantics,

– GET is used to retrieve data, fixtures, standings, odds, etc. with query parameters like include, select, and filters to tailor responses.
– Authentication is consistently required on each request, via an api_token in the query string or the Authorization header.
– Our documentation specifies supported status codes, methods (Allow header), and potential errors, ensuring predictable interactions.
– Additional support for optional request optimization (e.g., include, select, nested filters) shows how GET can be powerful yet safe and cache-friendly.

In summary, Sportmonks exemplifies clean, RESTful design:
– All interactions are routed through semantically aligned HTTP methods.
– Use of query parameters enhances efficiency without compromising method properties.
– Comprehensive docs (endpoints, filters, error codes) reinforce predictable, standards-compliant API use.

Understand your actions: HTTP methods explained

Every time your app interacts with Sportmonks’ API, it uses an HTTP method like GET, POST, or DELETE. These methods act as instructions, telling the server whether you’re requesting data, creating something new, or updating existing content. Used correctly, they make your integration predictable, efficient, and RESTful.

Sportmonks follows best practices in how these methods are used, GET for safe data retrieval, clear status codes for every response, and secure token-based authentication. Stick to the correct HTTP verbs, and you’ll build faster, cleaner, and more reliable football applications with Sportmonks.