CODEWITHSUNDEEP
apirestrestful-architecturehateoashypermedia
Paweł O.
Paweł O.

Reputation: 57

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}

Upvotes: 0

Views: 137

Answers (1)

Alex Marculescu
Alex Marculescu

Reputation: 5770

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.

Upvotes: 1

Related Questions