0

Please consider the following example (common in SaaS applications):

This is a SaaS that deals with Widgets.

  • You have an Account, that you authenticate via an API key. Each API key authenticates only one Account.
  • You have several Widgets under your Account. A Widget belongs to only one Account and can't be transferred to other Accounts.

The URL representation of a widget can be:

  1. https://api.domain.com/v0/accounts/{accountId}/widgets/{widgetId}

  2. https://api.domain.com/v0/widgets/{widgetId}

The difference is that route 1 makes has the accountId explicit and route 2 has it implicit (in the authentication via the API key).

Examples

In the wild there seems to be examples for both alternatives:

For example, Twilio API makes the accountId explicit. To make an outbound call:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXX/Calls.json \ --data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \ --data-urlencode "From=+15010000000" \ --data-urlencode "To=+12300000000" \ -u ACXXXXXXXXXXXXXXXXXXX:your_auth_token

and Stripe API has the accountId implicit. For example, to retrive your balance:

curl https://api.stripe.com/v1/balance \ -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:

What are the trade-offs to both alternatives (explicit and implicit)?

Improve this question

1 Answer 1

Reset to default
1

One advantage I can see in using case 1 (https://api.domain.com/v0/accounts/{accountId}/widgets/{widgetId}) is that the URL corresponds to a particular resource, whereas this is not true in case 2. The case 1 URL specifies a particular widget via its widgetId and the account with id accountId that it is associated with. In contrast it is not possible to determine the particular widget from the case 2 URL since it does not include the account id. From this argument case 1 is more 'RESTful'.

A similar question that discusses some further tradeoffs is here:

REST API design: POST (implicit userId) vs PUT (explicit userId)

Improve this answer
2
  • Thank you. If we asume that widgetId is unique (for example a GUID) then both would be equivalent in functionality? Commented May 29, 2018 at 13:42
  • If the widgetId was globally unique then yes, I'd definitely agree Commented May 31, 2018 at 8:55

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.