HTTP Methods in Duett OpenAPI

GET

The HTTP GET method is used to retrieve a representation of a resource. In the successful (or "happy") path, a GET request returns a JSON representation of the resource along with an HTTP response code of 200 (OK). In error cases, it often returns:

  • 404 (NOT FOUND): The resource does not exist.
  • 400 (BAD REQUEST): The request is malformed.

Per HTTP specification design, GET requests are read-only and should never modify data. This makes them a safe method.

Additionally, GET is idempotent, meaning multiple identical requests result in the same outcome as a single request.

Features of GET in Duett OpenAPI:
  • Supports filtering, sorting, and pagination. (Refer to the Query section for more details.)

GET {id}

Use GET {id} to retrieve a single resource by its unique identifier.

POST

The HTTP POST method is typically used to create new resources, especially resources that are subordinate to a parent resource. When posting to a parent resource, the service handles:

  • Associating the new resource with the parent.
  • Generating a unique ID or URI for the new resource.
On Success:

Returns the newly created resource along with a 201 (CREATED) status code.

Characteristics:
  • POST is not safe and not idempotent.
  • Multiple identical POST requests may create duplicate resources.

PATCH

The PATCH method is used to modify an existing resource. Unlike PUT, a PATCH request contains only the changes to be applied, not the entire resource representation.

Key Features:
  • The request body typically describes how the resource should be modified (e.g., using JSON Patch).
  • It updates the resource to create a new version based on the instructions in the request.
Characteristics:
  • PATCH is not safe and not idempotent, but it can be made idempotent.
  • Designing idempotent PATCH requests helps avoid issues caused by concurrent modifications.

PUT

The PUT method is used to update an existing resource by sending the complete updated representation to the server. Unlike PATCH, it requires the entire resource body of the "Create/Change"-model.

When the model has sub-objects, you can choose to update these objects or not. On customer, we have several sub-objects such as Address, ContactInfo, ContactPerson, PaymentInfo, InvoiceInfo and GroupAffiliations. If these are set to Null, PUT will not update these. If they are set to {} (empty object), the object will be removed.

NB: Remember that both PATCH and PUT can overwrite/remove changes and information in Duett Økonomi, so feel free to use Rowversion to see if there are more recent changes in Duett Økonomi. If you use PUT, remember that the entire object's properties must be included. If a property is omitted, it is set to Null, regardless of what the default value is at POST.

Key Features:
  • In Duett OpenAPI, PUT is used only for updates and does not support creating new resources (unlike some other APIs).
On Success:

Returns 204 (NO CONTENT) after a successful update.

Characteristics:
  • PUT is not safe but idempotent.
  • Sending the same PUT request multiple times results in the same final state of the resource.

DELETE

The DELETE method is used to remove a resource identified by a URI.

On Success:

Returns 204 (NO CONTENT) with an empty response body after a successful deletion.

Characteristics:
  • DELETE is idempotent.
  • If you issue a DELETE request for a resource that is already removed, subsequent calls will return 404 (NOT FOUND). Despite this, the final state remains consistent (the resource is gone).
Caveat:

Returning 404 after a second DELETE request is acceptable and accurately indicates that the resource no longer exists.