apirestrestful-architecturehateoashypermedia

Is this API structure HATEOAS compatible?


I'm wondering if the following structure of API links is HATEOAS compatible?

Especially I'm not sure of /create endpoint. Should it be at the entry level because user can create a group from there or is it fine to put it in /groups?

What are your thoughts about the rest? It should be also HAL compatible.

/groups
  /create
  /detail/{groupId}
    /update
    /delete
    /items
  /search{?page,size,sort}

Solution

  • HATEOAS (see Richardson's Maturity Model level 3) is all about links, so with HAL Browser this would look something like this:

    Root:

    {
      "_links": {
        "self": {
          "href": "/api/root"
        },
        "api:group-add": {
          "href": "http://apiname:port/api/group"
        },
        "api:group-search": {
          "href": "http://apiname:port/api/group?pageNumber={pageNumber}&pageSize={pageSize}&sort={sort}"
        },
        "api:group-by-id": {
          "href": "http://apiname:port/api/group/id" (OR "href": "http://apiname:port/api/group?id={id}")
        }
      }
    }
    

    The add would simply be a POST to that endpoint, and then you'd have 2 GET methods.

    Then once you drill down to a particular group (say #1):

    {
      "Id" : 1,
      "Name" : "test",
      "_links": {
        "self": {
          "href": "/api/group/1" (OR "/api/group?id=1")
        },
        "edit": {
          "href": "http://apiname:port/api/group/1"
        },
        "api:delete": {
          "href": "http://apiname:port/api/group/1"
        },
        "api:items-query": {
          "href": "http://apiname:port/api/bonus?groupId=1"
        }
      }
    }
    

    Here, the edit would simply be a PUT, and then you'll need a DELETE (see level 2 of REST in that same link), as for the items, you probably know best if they are just a property, or another endpoint; you could even embed them to be returned in the same call that's retrieving a group.