I know that these type of questions have been asked before. I have solution for my problem and I want to know if I am breaking REST or HTTP principals anywhere.
In my system I have a resource called member which supports usual GET/POST/PUT operations. Member has a status of Active and Disabled. I need to model the operation of disabling the user. I understand why following would be a bad idea from REST perspective
POST api/member/john.smith/disable
I have read a solution to accept a resource that represents the request to disable a member, something like below
public class DisableMemberRequest
{
public string Username {get; set;}
}
And then a POST on above resource
POST api/DisableMemberRequest
While this approach sounds reasonable, I feel this is not right in terms of clean API interfaces. It can be debatable whether the response of the above request should be a 200 OK or 201 Created or 202 Accepted.
I am thinking, I would crate a new resource called DisabledMember and a PUT on this resource would mean that particular member should be disabled as below
PUT api/disabledmember/john.smith
This looks to be a perfectly valid design from REST/HTTP perspective to me. But I am no expert and would like to validate this with people who have been doing this for long time.
EDIT
I am adding these details after interacting with fellow programmers on this page. The process of disabling the member is not only about setting a status flag on the member. There are other workflows that need to be triggered when a member is disabled.
One way that I like to do things like this is to define a resource that represents the set of disabled members. To disable a member, you add that member to the set of disabled members. It could look something like this.
POST /api/DisabledMembers
Content-Type: text/uri-list
http://example.org/api/members/john.smith
If you want to reverse the operation, you could do
POST /api/ActiveMembers
Content-Type: text/uri-list
http://example.org/api/members/john.smith
This approach has the benefit of the fact that doing GET /api/DisabledMembers would be a perfectly natural thing to do. Also, by using text/uri-list it becomes easy to disable/reactivate a set of members all at the same time.
Your first two suggestions both smell a little, because they have a verb in the URL. Good RESTful architecture defines noun-like resources only, as the HTTP protocol defines the set of verbs applicable to those resources.
The other suggestion is interesting, but PUT suggests you can then perform a GET to obtain a representation of the thing you just put there, which doesn't make a whole lot of sense in this context.
From what you're saying, there's a significant process to enabling or disabling a user's account and that you're not comfortable with that being a PUT or PATCH operation to simply "flip" a value from true to false. If this takes some time, has transient state and is likely to be something you want to be able to expose to API consumers so they are aware of the process, it makes sense to define the process itself as a kind of resource:
Start deactivation:
POST api/members/deactivations
Get the current state of a deactivation or report on activities that have taken place:
GET api/members/deactivations/john.smith
Cancel a deactivation in-progress (optional):
DELETE api/members/deactivations/john.smith
If you could reactivate an account, it could follow a similar pattern.
If you feel that there's not enough substance to these workflows to justify them as their own resources, or you just wouldn't know what to put in response to GET, then it suggests that the workflow isn't so significant that it can't simply be hidden from the API users and triggered as a side-effect of changing the user's active value.
Just answered a similar question in here.
The practical way of thinking or applying REST as the starting point (at least it works for me) is to think in the following ways:
1) Use only HTTP ‘GET/POST/PUT/DELETE’ as the way to model your domain ‘actions’ . Just like when you dealing with database, all your actions are mapped to CURD.
2) URI/URL is to identify resources only. Should never have any ‘actions’ in your URI.
3) The data exchanged should be in the body of the HTTP messages.
Just to simplify the discussions, not getting into how to model the data itself
Tragedian’s solution looks clean.
Updated to address #Suhas' comments
REST is not about naming convention. It is all about how to think about the resources instead of ‘actions’ when designing REST API. Should always think about 'Nonce' like resource in URL/URI. You already have all the CURD actions that the domain actions should be mapped to and to manipulate the resources in the URL.
I like Tragedian's solution, just for the discussion sake, we can refactor Tragedian's solution with a similar set of nonce and different URL pattern to 'better' fit the different domain usage. The following may not be the best solution for the domain but they are equivalently RESTful.
Remove membership
DELETE api/membership/[member-id]/
Get membership status
GET api/membership/[member-id]/status/
Add membership
POST api/membership/[member-id]/
Updated to address the issue with "DisabledMember” as the resource
If using “PUT DisabledMember” to do ‘disable member’ as suggested by Suhas
Then what will the following actions on ‘DisabledMember” resource mean?
DELETE DisabledMember → activate it again??
POST DisabledMember -> ??
GET DisabledMember – this is an easy one ☺
With this design, it actually “disguises” the action ‘disable’ in the resource.
You may still can force fit it to do what you want but it wont be as Restful to me.
Member has a status of Active and Disabled
So status is a property of Member entity/resource; in that case why you don't want to use simply PUT method on Member resource with status set to Disabled?
If it's a short process to disable the user, why not use HTTP PATCH?
See this answer to a similar question
Related
I have a resource called “subscriptions”
I need to update a subscription’s send date. When a request is sent to my endpoint, my server will call a third-party system to update the passed subscription.
“subscriptions” have other types of updates. For instance, you can change a subscription’s frequency. This operation also involves calling a third-party system from my server.
To be truly “RESTful,” must I force these different types of updates to share an endpoint?
PATCH subscriptions/:id
I can hypothetically use my controller behind the endpoint to fire different functions depending on the query string... But what if I need to add a third or fourth “update” type action? Should they ALL run through this single PATCH route?
To be truly “RESTful,” must I force these different types of updates to share an endpoint?
No - but you will often want to.
Consider how you would support this on the web: you might have a number of different HTML forms, each accepting a slightly different set of inputs from the user. When the form is submitted, the browser will use the input controls and form metadata to construct an HTTP (POST) request. The target URI of the request is copied from the form action.
So your question is analogous to: should we use the same action for all of our different forms?
And the answer is yes, if you want the general purpose HTTP application to understand which resource is expected to change in response to the message. One reason that you might want that is cache invalidation; using the right target URI allows all of the caches to understand which previously cached responses should not be reused.
Is that choice free? no - it adds some ambiguity to your access logs, and routing the request to the appropriate handler in your code takes a bit more work.
Trying to use PATCH with different target URI is a little bit weird, and suggests that maybe you are trying to stretch PATCH beyond the standard constraints.
PATCH (and PUT) have remote authoring semantics; what they mean is "make your copy of the target resource look like my copy". These are methods we would use if we were trying to fix a spelling error on a web page.
Trying to change the representation of one resource by sending a remote authoring request to a different resource makes it harder for the general purpose HTTP application components to add value. You are coloring outside of the lines, and that means accepting the liability if anything goes wrong because you are using standardized messages in a non standard way.
That said, it is reasonable to have many different resources that present representations of the same domain entity. Instead of putting everything you know about a user into one web page, you can spread it out among several that are linked together.
You might have, for example, a web page for an invoice, and then another web page for shipping information, and another web page for billing information. You now have a resource model with clearer separation of concerns, and can combine the standardized meanings of PUT/PATCH with this resource model to further your business goals.
We can create as many resources as we need (in the web level; at the REST level) to get a job done. -- Webber, 2011
So, in your example, would I do one endpoint like this user/:id/invoice/:id and then another like this user/:id/billing/:id
Resources, not endpoints.
GET /invoice/12345
GET /invoice/12345/shipping-address
GET /invoice/12345/billing-address
Or
GET /invoice/12345
GET /shipping-address/12345
GET /billing-address/12345
The spelling conventions that you use for resource identifiers don't actually matter very much.
So if it makes life easier for you to stick all of these into a hierarchy that includes both users and invoices, that's also fine.
A few time ago I participate from a interview where had a question about REST modelling, and how the best way to implement it. The question was:
You have an REST API where you expose a method to consult the distance between two point, although you must save each request to this method to expose the request history.
And I was questioned about which HTTP method should be used on this case, for me the logic answer in that moment was the GET method (to execute the both actions). After this the interviewer asked me why, because since we are also storing the request, this endpoint is not idempotent anymore, after that I wasn't able to reply it. Since this stills on my mind, so I decided to verify here and see others opinions about which method should be used for this case (or how many, GET and POST for example).
You have an REST API where you expose a method to consult the distance between two point, although you must save each request to this method to expose the request history.
How would you do this on the web? You'd probably have a web page with a form, and that form would have input controls to collect the start and end point. When you submit the form, the browser would use the data in the controls, as well as the form metadata and standard HTML processing rules to create a request that would be sent to the server.
Technically, you could use POST as the method of the form. It's completely legal to do that. BUT, as the semantics of the request are "effectively read only", a better choice would be to use GET.
More precisely, this would mean having a family of similar resources, the representation of which includes information about the two points described in the query string.
That family of similar resources would probably be implemented on your origin server as a single operation/route, with a parser extracting the two points from the query string and passing them along to the function as arguments.
the interviewer asked me why, because since we are also storing the request, this endpoint is not idempotent anymore
This is probably the wrong objection - the semantics of GET requests are safe (effectively read only). So the interview might argue that saving the request history is not read only. However, this objection is invalid, because the semantic constraints apply to the request message, not the implementation.
For instance, you may have noticed that HTTP servers commonly add an entry to their access log for each request. Clearly that's not "read only" - but it is merely an implementation detail; the client's request did not say "and also log this".
GET is still fine here, even though the server is writing things down.
One possible objection would be that, if we use GET, then sometimes a cache will return an previous response rather than passing the request all the way through to the origin server to get logged. Which is GREAT - caches are a big part of the reason that the web can be web scale.
But if you don't want caching, the correct way to handle that is to add metadata to the response to inhibit caching, not to change the HTTP method.
Another possibility, which is more consistent with the interviewer's "idempotent" remark, is that they wanted this "request history" to be a resource that the client could edit, and that looking up distances would be a side effect of that editing process.
For instance, we might have some sort of an "itinerary" resource with one or more legs provided by the client. Each time the client modifies the itinerary (for example, by adding another leg), the distance lookup method is called automatically.
In this kind of a problem, where the client is (logically) editing a resource, the requests are no longer "effectively read only". So GET is off the table as an option, and we have to look into the other possibilities.
The TL;DR version is that POST would always be acceptable (and this is how we would do it on the web), but you might prefer an API style where the client edits the representation of the resource locally, in which case you would let the client choose between PUT and PATCH.
I know the use of http verbs is based on standard specification. But my question if I use "GET" for update operations and write a code logic to update, does it create issues in any scenario? Apart from the standard, what else could be the reason to use these verbs for a specific purpose only?
my question if I use "GET" for update operations and write a code logic to update, does it create issues in any scenario?
Yes.
A simple example - suppose the network between the client and the server is unreliable; specifically, for a time, HTTP responses are being lost. A general purpose component (like a web proxy) might time out, and then, noticing that the method token of the request is GET, resend the request a second/third/fourth time, with your server performing its update on every GET request.
Let us further assume that these multiple update operations lead to an undesirable outcome; where do we properly affix blame?
Second example: you send someone a copy of the link to the update operation, so that they can send you a request at the appropriate time. But suppose you send that link to them in an email, and the email client recognizes the uri and (as a performance optimization) pre-fetches the link, triggering your update operation too early. Where do we properly affix the blame?
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 -- Fielding, 2002
In these, and other examples, blame is correctly affixed to your server, because GET has a standardized meaning which include the constraint that the semantics of the request are safe.
That's not to say that you can't have side effects when handling a GET request; "hit counters" are almost as old as the web itself. You have a lot of freedom in your implementation; so long as you respect the uniform interface, there won't be too much trouble.
Experience report: one of our internal tools uses GET requests to trigger scheduling; in our carefully controlled context (which is not web scale), we get away with it, and have for a very long time.
To borrow your language, there are certainly scenarios that would give us problems; but given our controls we manage to avoid them.
I wouldn't like our chances, though, if requests started coming in from outside of our carefully controlled context.
I think it's a decent question. You're asking a hypothetical: is there any value to doing the right other than that's we agree to use GET for fetching? e.g.: is there value beyond the fact that it's 'semantically nice'. A similar question in HTML might be: "Is it ok to use a <div> with an onclick instead of a <button>? (the answer is no).
There certainly is. Clients, servers and intermediates all change their behavior depending on what method is used. Even if your server can process GET for updates, and you build a client that uses this, your browser might still get confused.
If you are interested in this subject, don't ask on a forum; read the spec. The HTTP specification tells you what clients, servers and proxies should do when they encounter certain methods, statuses and headers.
Start at RFC7231
I am developing my own REST API and was looking for other well-established APIs to see what they do when they have a need to expose some sort of action that can be made on a resource. One that came up was the ability to star and unstar a repository/gist on GitHub. According to their docs, you can star with PUT /gists/{gist_id}/star, and unstar with DELETE /gists/{gist_id}/star.
This is what the docs say about the HTTP verbs:
PUT Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE Used for deleting resources.
Delete makes sense to me, but why would PUT be used? Since you can GET /gists/{gist_id}/star it seems "star" is some sort of functional resource. So I guess I'm just wondering why PUT instead of POST?
So I guess I'm just wondering why PUT instead of POST?
PUT, in HTTP, has somewhat tighter constraints on its semantics than POST does -- for instance, the semantics of PUT are idempotent, which is a convenient thing to know when you are sending requests over an unreliable network; PUT tells you that there won't be a problem if the server receives more than one copy of the request message.
(This is a lot like asking about why GET instead of POST, except that the differences are smaller)
Which is why when you have a simple remote authoring use case, like uploading a document to a document store, that PUT is the superior choice -- because it allows general purpose clients (like browsers) to do useful things without needing extra out of band information.
https://docs.github.com/en/rest/overview/resources-in-the-rest-api#http-verbs does NOT define the semantics of the HTTP methods. The standardized definitions of GET, PUT, POST and so on are in RFC 7231.
If you review the RFC, you'll discover that the semantics of HTTP PUT also cover "create":
The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.
"Make your copy of this document look like my copy" is a perfectly reasonable way to communicate information to the server, and the meaning of that message doesn't really depend at all on whether or not the server already knows about the document when the request is processed.
I am developing my own REST API
Do make sure you review Jim Webber's 2011 talk, which I think goes a long way toward clarifying how web based API are "supposed" to work.
One reason I could see is that the star “exists”, and these routes are just toggling some sort of “active” property on the star. So you wouldn’t use POST because you’re not creating the star, just toggling its active property.
Edit: this is also just a guess based on how I’d implement something like this, as their docs are kind of sparse.
I'm building a REST API and I'm trying to keep it as RESTful as possible, but some things are still not quite clear for me. I saw a lot of topic about similar question but all too centered about the "simple" problem of updating data, my issue is more about the business logic around that.
My main issue is with business logic triggered by partial update of a model. I see a lot of different opinion online about PATCH methods, creating new sub-ressources or adding action, but it often seems counter productive with the REST approach of keeping URI simple and structured.
I have some record that need to be proceeded ( refused, validated, partially validated ..etc ), each change trigger additional actions.
If it's refused, an email with the reason should be sent
if it's partially validated, the link to fulfill the missing data is sent
if it's validated some other ressources must be created.
There is a few other change that can be made to the status but this is enough for the example.
What would be a RESTful way to do that ?
My first idea would be to create actions :
POST /record/:id/refuse
POST /record/:id/validate ..etc
It seems RESTful to me but too complicated, and moreover, this approach means having multiple route performing essentially the same thing : Update one field in the record object
I also see the possibility of a PATCH method like :
PATCH /record/:id in which I check if the field to update is status, and the new value to know which action to perform.
But I feel it can start to be too complex when I will have the need to perform similar action for other property of the record.
My last option, and I think maybe the best but I'm not sure if it's RESTful, would be to use a sub-ressource status and to use PUT to update it :
PUT /record/:id/status, with a switch on the new value.
No matter what the previous value was, switching to accepted will always trigger the creation, switching to refused will always trigger the email ...etc
Are those way of achieving that RESTful and which one make more sense ? Is there other alternative I didn't think about ?
Thanks
What would be a RESTful way to do that ?
In HTTP, your "uniform interface" is that of a document store. Your Rest API is a facade, that takes messages with remote authoring semantics (PUT/POST/PATCH), and your implementation produces useful work as a side effect of its handling of those messages.
See Jim Webber 2011.
I have some record that need to be proceeded ( refused, validated, partially validated ..etc ), each change trigger additional actions.
So think about how we might do this on the web. We GET some resource, and what is returned is an html representation of the information of the record and a bunch of forms that describe actions we can do. So there's a refused form, and a validated form, and so on. The user chooses the correct form to use in the browser, fills in any supplementary information, and submits the form. The browser, using the HTML form processing rules, converts the form information into an HTTP request.
For unsafe operations, the form is configured to use POST, and the browsers therefore know that the form data should be part of the message-body of the request.
The target-uri of the request is just whatever was used as the form action -- which is to say, the representation of the form includes in it the information that describes where the form should be submitted.
As far as the browser and the user are concerned, the target-uri can be anything. So you could have separate resources to handle validate messages and refused messages and so on.
Caching is an important idea, both in REST and in HTTP; HTTP has specific rules baked into it for cache invalidation. Therefore, it is often the case that you will want to use a target-uri that identifies the document you want the client to reload if the command is successful.
So it might go something like this: we GET /record/123, and that gives us a bunch of information, and also some forms describing how we can change the record. So fill one out, submit it successfully, and now we expect the forms to be gone - or a new set of forms to be available. Therefore, it's the record document itself that we would expect to be reloading, and the target-uri of the forms should be /record/123.
(So the API implementation would be responsible for looking at the HTTP request, and figuring out the meaning of the message. They might all go to a single /record/:id POST handler, and that code looks through the message-body to figure out which internal function should do the work).
PUT/PATCH are the same sort of idea, except that instead of submitting forms, we send edited representations of the resource itself. We GET /record/123, change the status (for example, to Rejected), and then send a copy of our new representation of the record to the server for processing. It would therefore be the responsibility of the server to examine the differences between its representation of the resource and the new provided copy, and calculate from them any necessary side effects.
My last option, and I think maybe the best but I'm not sure if it's RESTful, would be to use a sub-resource status and to use PUT to update it
It's fine -- think of any web page you have ever seen where the source has a link to an image, or a link to java script. The result is two resources instead of one, with separate cache entries for each -- which is great, when you want fine grained control over the caching of the resources.
But there's a trade - you also need to fetch more resources. (Server-push mitigates some of this problem).
Making things easier on the server may make things harder on the client - you're really trying to find the design with the best balance.