The REST API Maturity, categorizes APIs into levels that show how effectively they leverage RESTful principles. Here’s a breakdown of each level with examples:

Level 0: Plain Old XML (POX) or RPC

At this level, the API is essentially a single endpoint that accepts requests and returns data, with no emphasis on using HTTP methods or resources. It behaves like a Remote Procedure Call (RPC) endpoint.

• Example:
  • Endpoint: POST /api
  • Request: { "action": "getUser", "userId": 123 }
  • Response: { "user": { "id": 123, "name": "John Doe" } }

Here, the server just performs actions based on the "action" parameter, rather than defining different resources.

Level 1: Resource-Based

At Level 1, the API introduces resources, with unique URIs representing each resource. However, it might still use only a single HTTP method (often POST) and lack standard HTTP status codes.

• Example:
  • Endpoint: POST /api/users
  • Request: { "userId": 123 }
  • Response: { "user": { "id": 123, "name": "John Doe" } }

Now, resources are used (/users), but the API still relies mainly on a single method for all operations.

Level 2: HTTP Verbs

At Level 2, the API fully adopts HTTP methods, such as GET, POST, PUT, and DELETE, to represent actions on resources, and returns appropriate HTTP status codes. This follows REST conventions more closely.

• Example:
  • GET /api/users/123 - Retrieves user with ID 123
  • POST /api/users - Creates a new user
  • PUT /api/users/123 - Updates user with ID 123
  • DELETE /api/users/123 - Deletes user with ID 123
  • HTTP Status Codes: 200 OK, 201 Created, 404 Not Found, 204 No Content

At this level, resources and HTTP methods align, making it more RESTful.

Level 3: Hypermedia Controls (HATEOAS - Hypermedia as the Engine of Application State)

At Level 3, the API not only follows resource structure and HTTP verbs but also includes hypermedia controls. This means responses include links to related resources or actions, allowing clients to discover and navigate the API dynamically.

• Example:

  • GET /api/users/123
  • Response:

  {
    "id": 123,
    "name": "John Doe",
    "_links": {
      "self": { "href": "/api/users/123" },
      "friends": { "href": "/api/users/123/friends" },
      "posts": { "href": "/api/users/123/posts" }
    }
  }
  

Here, each response provides links to other resources or possible actions (friends, posts). The client can use these links to interact with the API without needing hardcoded URIs.

Summary

• Level 0: Single endpoint, action-based (RPC-like).
• Level 1: Resources, but limited HTTP verb use.
• Level 2: Resources with HTTP verbs and status codes.
• Level 3: Hypermedia controls (HATEOAS) for navigation and discovery.

Level 3 is considered fully RESTful and provides the most flexibility for client applications, allowing them to navigate the API without prior knowledge of all URIs.