0

Basing this question off of the example here What are best practices for REST nested resources?

What would the endpoint look like if you wanted to fetch the company that an employee works for? The options I can see are:

  1. GET /companies?employeeId=x would presumably return a list of companies where employeeId=x
  2. GET /companies/by-employee/{employeeId} would return a single company. This endpoint takes some inspiration from the /dev/disks/ symlinks on Linux systems. It basically aliases company by all of their child entities
  3. GET /employees/{employeeId}/company would return a single company and inverts the relationship between employees and companies

1 Answer 1

1

What would the endpoint look like if you wanted to fetch the company that an employee works for?

REST doesn't care what spelling you use for your resource identifiers.

Think about the way a browser works when it loads an HTML page. Suppose there is an img tag; the tag gives the browser the semantic context that it needs, so that it can send a request for the image (and in particular, send a request with its preferred image types). The browser doesn't have to parse the URL, looking for file extensions or anything like that to figure out that the resource is an image.

Trying to encode your semantics into the URI is the wrong way around; the semantics belong in the links.

If you are designing a REST API, what you want is something analogous to

Link: </F4EEFDD3-44D9-41AD-8299-620ECD8765DB>; rel="https://schema.org/Organization"

Translation: this link "points to" a resource that is the organization of the current context.

Client and Server need to have a contract that describes what links are possible, and what they mean, in just the same way that the HTML specification describes the semantics of a elements, img elements, and so on.

If you have that piece in place, then clients follow protocols by following links, and the servers can choose any link spellings that they like (for instance, to take best advantage of caching).

As you can see, from the perspective of the client, the spelling of the identifier doesn't matter very much (in a very similar way to the fact that the spelling of a variable name doesn't matter very much).

Link: </F4EEFDD3-44D9-41AD-8299-620ECD8765DB>; rel="https://schema.org/Organization"
Link: </companies?employeeId={employeeId}>; rel="https://schema.org/Organization"
Link: </companies/by-employee/{employeeId}>; rel="https://schema.org/Organization"
Link: </employees/{employeeId}/company>; rel="https://schema.org/Organization"

/companies?employeeId={employeeId} is a convenient identifier because you can also leverage it via HTML's form processing rules.

/companies/by-employee/{employeeId} and /employees/{employeeId}/company might be convenient because you can leverage relative resolution and dot segments to link to other resources at convenient locations in the identifier hierarchy.

Recommended viewing: Tilkov's REST: I Don't Think It Means What You Think It Means.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.