REST URI design

Question

In developing a RESTFul web service, I'm confused in modelling of my request entity. Should all the data required to process the request be a part of the entity or should I move some of the data in to the URL path (given that I've logical hierarchy among this data).

For example:

Path

/api/payment/3pResponse

Entity Schema

{
  "marketplacedId" : String,
  "customerId: String,
  "contractId: String,
  "planId": String,
  "3pResonse" : {},
  "3pResponseURI" : "string" 
}

versus

Path

/api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId}/plans/{plandId}/3pResponse

Entity Schema

{
  "3pResonse" : {},
  "3pResponseURI" : "string" 
}

Please no that resources along the path such as the /api/payment/marketplaces/{mktId} may not really exist in my application.

Either of the two would technically work, but I want to understand the best practices around entity modelling in such scenarios.

What's the UseCase? What's the Resource in your case. Is it a POST, PUT, GET... Operation you are talking about? Do you expect idempotency, ....? — andih, Jul 12 '16 at 09:29
It also depends on how you want to access your resources. Do you want to access for example the customers directly, that's the reason why I'm asking for your UseCase(s). — andih, Jul 12 '16 at 10:57

andih · Accepted Answer · 2016-07-13T06:10:39.267

When you design your REST API you map your functional requirements to the your resources similar to object oriented design methods.

Resources are a generic concept like Objects. A Resource has two essential properties it is identifiable and has one or more representations accessible from the outside.

In your first example /api/payment/3pResponse you have only a 3PResponse Resource which you completely update using the PUT method.

When you try to access them you may identify the resource via matrix parameter. (that's only one way how you could do it, there are also others)

/api/payment/3pResponse;marketPlace=x;customerId=y;contractId=z;planId=k

In your second approach

/api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId}/plans/{plandId}/3pResponse

3pResponse is a sub resource of marketplaces, customers, contracts and plans.

Using this approach one may could have the idea that there is also a resource /api/payment/marketplaces/ which returns a list of marketplaces or that there is a resource /api/payment/marketplaces/{mktId}/customers/{customerId}/contracts/{contractId} which returns a contract for a customer.

Your application is expected to return a useful result for these resources even when the client should not try to interpret your uri.

There is a nice presentation of Stefan Tilkov about REST API Design REST: I don't Think it Means What You Think it Does

More important than the actual design of your URIs and resources is that you keep your URIs stable.

Quote from Tim Berners-Lee: "Cool URIs don't change".

This was helpful. Going with the approach that uses the query parameters to map the resource. Thanks! — Bazooka, Jul 13 '16 at 06:19

REST URI design

1 Answers1