CODEWITHSUNDEEP
resturiapi-design
Nithin Satheesan
Nithin Satheesan

Reputation: 1716

REST URI design: Resource with plural name

I have a collections of customers and each customer has a relationships resource that looks like this:

{
  "customerId" : "string",
  "accounts" : [{
    "accountId" : "string",
     ...
  }],
  "profiles" : [{
    "profileId" : "string",
     ...
  }]
}

I am building a REST api to provide access to this resource and sub resources like accounts and profiles.

This is the URIs that I came up with:

  1. /customers/{id}/relationships - To return the above resource
  2. /customers/{id}/relationships/accounts - To return accounts sub resource
  3. /customers/{id}/relationships/profiles - To return profiles sub resource

But one issue I see is that relationships resource looks like a collection. So it will be expected to have a {relationshipId} after that. But actually it is a single resource. How can I design URIs for this?

Upvotes: 0

Views: 104

Answers (2)

Amit Khanna
Amit Khanna

Reputation: 489

You need to decide if relationships is a document or a collection. See this for definitions:

https://restfulapi.net/resource-naming/

If you think it is a collection then /customers/{id}/relationships/accounts is correct where accounts is an id of the resource in collection.

If you think of it as a document then you are requesting a limited view of the document and you can use something like /customers/{id}/relationships?$select=accounts if you wish to follow it the OData way

https://learn.microsoft.com/en-us/aspnet/web-api/overview/odata-support-in-aspnet-web-api/using-select-expand-and-value#using-select

Upvotes: 0

Leigh Bicknell
Leigh Bicknell

Reputation: 872

If 'relationships' is a single object and not a collection you could go several ways.

  1. Remove it entirely so you have /customers/{id}/accounts and /customers/{id}/profiles
  2. Rename it to something else /customers/{id}/related/accounts
  3. Leave it as is... This still works as 'accounts' and 'profiles' become id's beneath the relationships collection (/customers/{id}/relationships/{id(accounts|profiles)}

It is always good to follow standards. But often you can spend too long worrying about minor issues in which ultimately no matter which way you go, will not make a massive difference.

Upvotes: 1

Related Questions