HTTP API and REST principles

An API defines a stable way for two software programs to communicate. On the web, the interface often sends an HTTP request to a server, which returns a structured response.

Interface → requête HTTP → API → logique métier → base de données
Interface ← réponse HTTP  ← API ← résultat

REST is an architectural style, not an additional protocol. An API REST generally represents its domain with resources identified by URLs and uses HTTP rules.

Anatomy of a query

• a method: GET, POST, PUT, PATCH or DELETE;
• a URL to a resource;
• headers, for example the accepted format;
• sometimes a body, often encoded in JSON.

POST /api/cards HTTP/1.1
Content-Type: application/json

{
  "question": "Que signifie HTTP ?",
  "answer": "Hypertext Transfer Protocol"
}

Common methods

Method	Habitual intention
GET	Read a resource without modifying it
POST	Create a resource or trigger processing
PUT	Replace a known resource
PATCH	Edit part of a resource
DELETE	Delete a resource

Useful response codes

• 200 OK: the request was successful;
• 201 Created: a resource has been created;
• 204 No Content: success with no content to return;
• 400 Bad Request: the request is invalid;
• 401 Unauthorized: authentication is required or invalid;
• 403 Forbidden: the identity is known but the action is prohibited;
• 404 Not Found: the requested resource does not exist;
• 409 Conflict: the current state prevents the operation;
• 500 Internal Server Error: The server encountered an unexpected error.

What to remember

The HTTP code describes the technical result of the request. The response must also provide an actionable message, without revealing sensitive information.