Today I Learned

A GET request expresses the user's intent to not have any side effects. Naturally, there will always be side effects on the server like log entries for example, but the important distinction here is whether the user had asked for a side effect or not.

Another reason to stay away from GET surfaces if you respond with the recommended 201 Created response for a request where the resource is being created on the server. The next request would result in a different response with status 200 OK and thus it cannot be cached as is usually the case with GET requests.

Instead, I would suggest to use PUT, which is defined as

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem.

In the above form, it should be considered a "create or update" action.

To implement pure "get or create" you could respond with 409 Conflict in case an update would result in a different state.

However, especially if you are looking for idempotence, you might find that "create or update" semantics could actually be a better fit than "get or create". This depends heavily on the use case though.

source: https://stackoverflow.com/questions/21900868/best-http-method-for-get-or-create#:~:text=I'm%20writing%20an%20HTTP%20based%20API,%20and%20I%20have%20a

Idempotency

Api Design

In sofware and tech idempotency typically refers to the idea that you can perform an operation multiple times without triggering any side effects more than once.

Here's the main facts you need to know about idempotency:

Idempotency is a property of operations or API requests that ensures repeating the operation multiple times produces the same result as executing it once.
Safe methods are idempotent but not all idempotent methods are safe.
HTTP methods like GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are idempotent, while POST and PATCH are generally non-idempotent.

Source: https://blog.dreamfactory.com/what-is-idempotency#:~:text=Idempotency%20is%20a%20property%20of,all%20idempotent%20methods%20are%20safe.

Get endpoints can only have params

Api Design

GET requests are designed to retrieve data from a server, similar to fetching a document from a library catalog.
Since you're "getting" info, a body (like a new book) wouldn't be appropriate. Params (like search terms) are used to filter or specify the data you want.
This design keeps GET requests simple and avoids ambiguity.

HATEOAS - Hypermedia as the Engine of Application State

Api Design

HATEOAS (Hypermedia as the Engine of Application State) is a design principle within RESTful APIs. It dictates that the server dynamically informs the client of available actions and related resources through hypermedia elements embedded within the response.

Imagine you're exploring a choose-your-own-adventure storybook. HATEOAS (Hypermedia as the Engine of Application State) is like the book itself guiding you through the adventure.

How it works:

You reach a point in the story (like a new level in a game).
The book (the application) presents you with the available options for what you can do next (like fight a monster or solve a puzzle). These are the hypermedia elements.
You choose an option by following the provided link or instructions.
The story then unfolds based on your choice, revealing new options and progressing the state of the application.

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://adventure-works.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://adventure-works.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

Organize the API design around resources

Api Design

In 2008, Leonard Richardson proposed the following maturity model for web APIs:

Level 0: Define one URI, and all operations are POST requests to this URI.
Level 1: Create separate URIs for individual resources.
Level 2: Use HTTP methods to define operations on resources.
Level 3: Use hypermedia (HATEOAS, described below).

Level 3 corresponds to a truly RESTful API according to Fielding's definition. In practice, many published web APIs fall somewhere around level 2.