I'm designing a REST-style API for a service that provides analysis of clinical data. The API allows a user to create a Patient resource. This resource provides input data to the server-side analysis.
Creation of a Patient is neither safe nor idempotent (the server assigns an ID) so POST is used, POST Patients
The Patient resource can be large, so it has sub-resources, e.g. Medications, that can be updated. Updating Medications is idempotent as the entire set of med's will be replaced, so PUT is used.
Clinical analysis is triggered by requesting POST /Patients/{patientId}/analysisResults . Alternatively, a user can request that analysis results are returned in the response of the POST /Patients request; this saves an additional HTTP round-trip.
My problem is this; users want results of the analysis included in the response to an update (PUT) to Patient/Medications - understandable as they don't want to make a second request to retrieve the results. Thus PUT Patient/Medications would be idempotent with regards to the Patient resource but not in terms of all resources as a new analysisResults sub-resource will be created. Should I:
a) Enable this with a PUT.
b) Enable this with a POST.
c) Insist that a separate call is required to create new
analysisResults even though this will increase the overall
response times for the end-user?
Option C if you wish to remain RESTful.
Options A and B will most likely weaken the properties that REST is designed to give you, caching is the one that comes directly to mind.
If this is HTML based, the response will include a link to the analysisReport resource to allow the user to drive the application to somewhere useful.
Related
The data, being sent over a PUT/PATCH/POST request, ultimately ends up in the database.
Now whether we are inserting a new resource or updating or modifying an existing one - it all depends upon the database operation being carried out.
Even if we send a POST and ultimately perform just an update in the database, it does not impact anywhere at all, isn't it?!
Hence, do they actually differ - apart from a purely conceptual point of view?
Hence, do they actually differ - apart from a purely conceptual point of view?
The semantics differ - what the messages mean, and what general purpose components are allowed to assume is going on.
The meanings are just those described by the references listed in the HTTP method registry. Today, that means that POST and PUT are described by HTTP semantics; PATCH is described by RFC 5789.
Loosely: PUT means that the request content is a proposed replacement for the current representation of some resource -- it's the method we would use to upload or replace a single web page if we were using the HTTP protocol to do that.
PATCH means that the request content is a patch document - which is to say a proposed edit to the current representation of some resource. So instead of sending the entire HTML document with PUT, you might instead just send a fix to the spelling error in the title element.
POST is... well, POST is everything else.
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding 2009
The POST method has the fewest constraints on its semantics (which is why we can use it for anything), but the consequence is that the HTTP application itself has to be very conservative with it.
Webber 2011 includes a good discussion of the implementations of the fact that HTTP is an application protocol.
Now whether we are inserting a new resource or updating or modifying an existing one - it all depends upon the database operation being carried out.
The HTTP method tells us what the request means - it doesn't place any constraints on how your implementation works.
See Fielding, 2002:
HTTP does not attempt to require the results of a GET to be safe. What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property (money, BTW, is considered property for the sake of this definition).
The HTTP methods are part of the "transfer of documents over a network" domain - ie they are part of the facade that allows us to pretend that the bank/book store/cat video archive you are implementing is just another "web site".
It is about the intent of the sender and from my perspective it has a different behaviour on the server side.
in a nutshell:
POST : creates new data entry on the server (especially with REST)
PUT : updates full data entry on the server (REST) or it creates a new data entry (non REST). The difference to a POST request is that the client specifies the target location on the server.
PATCH : the client requests a partial update (Id and partial data of entry are given). The difference to PUT is that the client sends not the full data back to the server this can save bandwidth.
In general you can use any HTTP request to store data (GET, HEAD, DELETE...) but it is common practice to use POST, PUT, and PATCH for specific and standardized scenarios. Because every developer can understand it later
They are slightly different and they bind to different concepts of REST API (which is based on HTTP)
Just imagine that you have some Booking entity. And yo perform the following actions with resources:
POST - creates a new resource. And it is not idempotent - if you sent the same request twice -> two bookings will be stored. The third time - will create the third one. You are updating your DB with every request.
PUT - updates the full representation of a resource. It means - it replaces the booking full object with a new one. And it is idempotent - you could send a request ten times result will be the same (if a resource wasn't changed between your calls)
PATCH - updates some part of the resource. For example, your booking entity has a date property -> you update only this property. For example, replace the existing date with new date which is sent at the request.
However, for either of the above - who is deciding whether it is going to be a new resource creation or updating/modifying an existing one, it's the database operation or something equivalent to that which takes care of persistence
You are mixing different things.
The persistence layer and UI layer are two different things.
The general pattern used at Java - Model View Controller.
REST API has its own concept. And the DB layer has its own purpose. Keep in mind that separating the work of your application into layers is exactly high cohesion - when code is narrow-focused and does one thing and does it well.
Mainly at the answer, I posted some concepts for REST.
The main decision about what the application should do - create the new entity or update is a developer. And this kind of decision is usually done through the service layer. There are many additional factors that could be done, like transactions support, performing filtering of the data from DB, pagination, etc.
Also, it depends on how the DB layer is implemented. If JPA with HIbernate is used or with JDBC template, custom queries execution...
There is a object of a name Car in the backend database. It contains several fields:
id
name
age
vinNumber
retailerId
There is also a API that elevates adding and editing the car:
POST /car - creates a car
PUT /car/{carId} - updates a car
User of a API can provide name, age and vinNumber while creating a car in a POST body.
When updating a car user can edit name and age. VinNumber is not enabled to be edited after creating a car.
Also retailerId is not editable since it comes from another system to the backend database.
Since that said, we have two fields that should not be edited with the API: vinNumber and retailerId.
So, taking into account REST idempotency, should the PUT request require the user of the API vinNumber and retailerId to be provided also, that were received earlier by GET request? In spite these parameters should not be editable?
An important thing to recognize -- the HTTP specification describes the semantics of an HTTP request; what does this message mean? It allows clients and servers implemented by different organizations to collaborate without requiring a direct partnership between the two.
The point being that a generic client can prepare a request for a generic server without needing out of band information.
PUT, semantically, is a request that the server change its current representation of a resource to match the client's local copy.
If "the server" was just an anemic data store (a facade in front of a file system, or a document database), then the effect of PUT at the server would just be to write the message-body as is into storage.
The point of REST, and the uniform interface, is that your server should always understand the messages the same way that the anemic facade understands them.
Similarly, your server should use the same shared semantics for its responses.
If the representations you are working with include vinNumber and retailId, then the client should be sending those fields unless the request is to remove them from the representation altogether (which may or may not be allowed, depending on whether or not they are required).
The server should understand that the request missing those fields is trying to remove them, and a request with new values in those fields is trying to change them. It can then decide what it wants to do with that request, and send the corresponding response.
Roy Fielding wrote about GET semantics in 2002:
HTTP does not attempt to require the results of a GET to be safe. What it does is require that the semantics of the operation be safe, and therefore it is a fault of the implementation, not the interface or the user of that interface, if anything happens as a result that causes loss of property (money, BTW, is considered property for the sake of this definition).
The same idea holds for PUT (and also the other HTTP methods); we hold the implementation responsible for loss of property if its handling of the request doesn't match the semantics.
According to the PUT request documentation- one should provide the complete data (ie vinNumber and retailerId also) - https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods
You could use PATCH instead for such cases.
Also what we done initally and i have see many times is POST /car/{carId}
I have 3 models: tournament, championship and competitor:
A tournament has many championships;
A championship belongs to tournament;
A championship has many competitors.
So, to list all the competitors from all the championships, the URL is:
GET https://base.com/tournament/{slug}/competitors
but to add a competitor, it is related to championship so:
POST https://base.com/championships/{id}/competitors
Is it ok that for the same model, two verbs (GET and POST) has differents URI? Otherwise, how should I do?
I fell like doing:
POST https://base.com/tournaments/{slug}/championships/{id}/competitors
has a no necessary field.
Is it ok that for the same model, two verbs (GET and POST) has differents URI?
This is likely to cause confusion for the API consumers, so I advise you use the same URI.
Bear in mind that the REST architectural style, described in the chapter 5 of Roy T. Fielding's dissertation, defines a set of constraints for applications build on the top of such architecture. But it says nothing about what the URIs must be like.
The examples shown in a popular article written by Martin Fowler explaining a model defined by Leonard Richardson suggest a URI structure that looks friendly and easy to read. While it may be desirable, it's not mandatory for REST applications.
There are plenty of valid approaches you could go for. If a competitor requires a championship to exist and a championship requires a tournament to exist, you could express such hierarchy using:
/tournaments/{slug}
/tournaments/{slug}/championships/{id}
/tournaments/{slug}/championships/{id}/competitors/{id}
But the last URI may be considered too long and may be hard to remember. So you could simply split it, then you don't need to send many parameters around:
/tournaments/{slug}
/championships/{id}
/competitors/{id}
If you need to perform any filtering, you could use query parameters. For example:
/championships/{id}?tournament={slug}
Reminder: REST doesn't care what spelling you use for your URI
Is it ok that for the same model, two verbs (GET and POST) has differents URI? Otherwise, how should I do?
It's OK, but there are certain costs associated with it.
Let's review what Fielding had to say (2008)
REST is intended for long-lived network-based applications that span multiple organizations.
The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.
One of the replication styles that Fielding identifies in his thesis is the cache; he goes on to add that style to his definition of REST
In order to improve network efficiency, we add cache constraints to form the client-cache-stateless-server style.... Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
In HTTP, the semantics of caching are defined in RFC 7234; Section 4.4 describes invalidation.
A cache MUST invalidate the effective Request URI (Section 5.5 of [RFC7230]) as well as the URI(s) in the Location and Content-Location response header fields (if present) when a non-error status code is received in response to an unsafe request method.
This means that communication passing through generic clients, that know nothing of the specifics of your protocols, can invalidate their local copy of stale representations, based on the metadata in the request and response.
(This was a bigger deal in the past, when we weren't encrypting all of the traffic; but it still applies to (a) the client's local cache and (b) the caching reverse proxy sitting in front of the domain model).
As far as REST is concerned, URI are opaque; there's no fundamental relationship between
/A
/A/B
/A/B/C
/A/B/D
/A/E
So if the caches see that /A/B should be invalidated, they can do that, but they won't do anything with the other URI.
For PUT, DELETE, PATCH -- the semantics of these methods is very specific to the effective request URI.
If you apply that same approach to POST, then you get cache invalidation "for free".
Walking through a simple example; imagine a web site, where we have
GET /superCoolResource
GET /superCoolResource/editForm
We want to induce some change in /superCoolResource, so we load the edit form, and submit it....
POST ...?
If we POST to /superCoolResource/editForm, then we are telling the client that the cached copy of the form should be reloaded if the POST is successful. But that probably isn't what we want -- it's more likely that the form stays the same, and the /superCoolResource is the thing that changes. That means we probably want to make /superCoolResource the target URI
GET /superCoolResource/editForm
200 OK
... <form action="/superCoolResource" method="POST"> ....
and magically the client's cache, the origin server's cache, and any intermediate caches that are privy to the conversation know to evict their old copy of /superCoolResource when the POST succeeds.
Say I have the need to expose a service, where I can request an analysis of a user over a specific range of time (common actions, activities, relationships, etc.).
I would immediately think of this as:
/users/{userId}/analyses - POST
/users/{userId}/analyses/{analysisId} - GET
The problem here, is where the 'analysis' resource comes into existence - it is inherently request-based as it is the service that will do this complex analysis, and also the service that has the most up-to-date state of the user data. In short, it doesn't exist prior to request.
My current thinking has me at three options for requesting an analysis for the first time (with retrieval being the same):
/users/{userId}/analyses?from=2017-01-01&to=2018-01-01 - GET
/users/{userId}/analyses - POST { "from": "2017-01-01", "to": "2018-01-01" }
/users/{userId}/analyses?from=2017-01-01&to=2018-01-01 - POST
I like the GET with query parameters, as I'm requesting a resource, and scoping the user data to be used, until I recognise that the resource could change between requests (based on data on the back end, or processing logic change), and that I would need to call a second time to POST this resource.
I like the POST with the request body, as I'm expecting a resource to be created, until I recognise that the state I've transferred, is not the state I would get back when I retrieve this later, nor is it even the same hypermedia type.
I like the POST with query parameters and no body, as I'm creating a resource and scoping that resource, but I'm still transferring a state that isn't the resource or end media type, and I've seen practically no other examples of POSTs with query parameters.
Anyone have experience with these kinds of actions in a RESTful manner?
In my opinion, using GET /users/{userId}/analyses?from=...&to=... is a good approach.
You request a resource of type analysis which means you have to use HTTP verb GET. You pass parameters to limit the scope. That the resource might change between two requests is not a problem. You request a resource in a specific state and this state might be changed right after your GET request. Compare this to a collection resource where other clients are allowed to POST something.
Using POST would imply that you want clients to create a resource of type analysis with all necessary data, which is from what I understand not true in your case. Your own counter-arguments for the second and third example are correct, in my opinion.
We have customers API that takes {customer-name, customer-mobile, customer-email} and creates customer in the database.
We also have order API that takes {productId, customer-name, customer-mobile, customer-email}.
The code for order API:
First creates customer based on {name,mobile,email} passed in the order API and return back customerId.
The {productId, customerId} further gets saved in the database in the order table.
Is this restful practice that one API is internally first creating some other resource?
Please note that its an over simplified example where API expects only one type of product in the order API.
It's fine for a single POST call to result in multiple resources being created. It's not generally the best idea but there are use cases where it makes sense - example cases might include (usual legal disclaimer... not limited to...)
the POST method is to the parent resource of all the created resources. So, a POST /accounts call might result in an /accounts/<accountId> resource being created but also an /accounts/<accountId>/tweets resource. In this instance, the /accounts/<accountId> parent is the 'actual' resource being created.
the POST method might create multiple resources representing multiple ways in which the resource may interact with other parts of the system. So, a POST /accounts response might create resources under /accounts/<accountId> and /users/<accountId> (because an account is-a user and user id are a super set of account ids, for arguments sake). However, the client really only gets told about the one under the '/accounts' path (via the Location header). The other created resource is basically a side-effect.
The key point, really, is that the POST method returns a single Location header - representing the 'primary' resource created - and that subsequent 'GET's on that URI are capable of locating any the other resources via links.
If you find yourself in a situation where creating multiple resources via a single POST request results in you having to return different values for the Location header, then something's wrong with your resource breakdown. It should be clear that a 'POST' will always create one particular type of resource, a URI to being returned in the header. Other resources might be created as side-effects.