restentity-model

REST URI design

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.

Solution

  • 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".