Question
How do we make a resource not a verb... but still maintain its special actions outside the default GET, POST, PUT, DELTE actions?
Details
I have been searching for some time now about the proper way to build a RESTful API. Tons of great information out there. Now I am actually trying to apply this to my website and have run into a few snags.
What our site does:
Our site site allows people to play games and win prizes.
The API will allow developers to build their own games and use our backend to collect, validate, store user information and give out prizes.
Scenario:
Developers will create their game then make a call to our API to let the player play the game (play_game). This play_game method combines multiple functions that we do not want a developer to run independently.
Here is what a play_game call does on the server:
It accepts player data the developer wants to store.
Validates the data (compares it to rules setup in the control panel)
Calculate what prize should be given.
Returns what prize was won to the Developer.
In addition there are multiple functions behind the scenes that get triggered like sending emails, etc.
Resource This is what our current resource looks like:
http://site.com/api/play_game
Issue:
This doesn't hold to the idea of no verbs in RESTful API's.
How do we make this resource not a verb... but still maintain its special actions outside the default GET, POST, PUT, DELTE actions?
Notes:
After asking this question I have decided to use Phil Sturgeons RESTful Framework... unless someone has a better idea.
You could place the following code into applications/routes.php
$route['(.*)'] = 'api';
Then you could access your API like:
http://site.com/play_game
BUT
You'll only have access to ONE controller only (your api controller)
Hope it helps
Related
I am planning to have these endpoints for our REST APIs.
PUT /tenant/:tenantId/users/save/:username
POST /tenant/:tenantId/users/invite
GET /tenant/:tenantId/users/fetch
GET /tenant/:tenantId/users/fetch/:username
PATCH /tenant/:tenantId/users/activate/:username
POST /tenant/:tenantId/groups/save/
Verbs such as save/fetch/activate are from the consistency point of view. Are these RESTFul according to the REST principles? How should these be changed if at all? Any recommendations?
According to this REST Resource Naming Guide:
RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.
And also
URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.
So let's take your first URI as example
PUT /tenant/:tenantId/users/save/:username
Here you are using the verb save. As mentioned before you should not be indicating a CRUD operation in the URI, in this case using a POST would be more appropriate.Here is a guide with the purpose of each HTTP verb. Knowing this, I think that for example a more appropriate URI for that case would be something like
POST /tenants/:tenantId/users/:username
In this cases:
GET /tenant/:tenantId/users/fetch
GET /tenant/:tenantId/users/fetch/:username
you should remove the fetch because you are already telling through the GET verb that data is being fetched. Same goes for the 6th example.
But, this doesn't mean that you can't use verbs in your URIs, in fact there is a specific category called controller which as mentioned in the same guide:
A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.
Use “verb” to denote controller archetype.
This controllers resources could go well (I asume) with for example your
GET /tenant/:tenantId/users/activate/:username.
But I would think that the verb activate should go last:
GET /tenant/:tenantId/users/:username/activate
First note: REST doesn't care what spelling conventions you use for your resource identifiers. Once you figure out the right resources, you can choose any identifiers for them that you like (so long as those identifiers are consistent with the production rules defined in RFC 3986).
"Any information that can be named can be a resource" (Fielding, 2000), but its probably most useful to think about resources as abstractions of documents. We use HTTP as an application protocol whose application domain is the transfer of documents over a network.
GET
This is the method we use to retrieve a document
PATCH
PUT
POST
These methods all indicate requests to edit a document (specifically, to edit the request target).
PUT and PATCH are each ask the server to make its copy of a document look like the client's local copy. Imagine loading a web page into an editor, making changes, and then "saving" those changes back to the server.
POST is less specific; "here's a document that we created by filling in a web form, edit yourself appropriately". It is okay to use POST: after all, the web was catastrophically successful and we're still using POST in our form submissions.
The useful work is a side effect of these edits.
Are these RESTFul according to the REST principles?
Do they work like a web site? If they work like a web site: meaning you follow links, and send information to the server by submitting forms, or editing the webpages and submitting your changes to the server, then it is REST.
A trick though: it is normal in REST that a single method + request uri might have different useful side effects. We can have several different HTML forms that all share the same Form.action. Uploading changes to an order document might have very different effects if the edits are to the shipping address vs to the billing information or the order items.
Normal doesn't mean obligatory - if you prefer a resource model where each form request goes to a specific resource, that can be OK too. You get simpler semantics, but you support more resources, which can make caching trickier.
I am new to designing REST APIs. I have trying to create following APIs for online game play
GET domain/api/games // return all games
POST domain/api/games // create a new game on behalf of current user
Now my issue is that when I try to create game using POST, I want userId to be sent to the API. I am not sure how to do this. Also note that I have another get API to get details of individual game, something like
GET domain/api/games/{gameId}
so I cannot pass userId to POST like domain/api/games/{useID} as it will conflict will above API.
So how do I pass usedId to POST. Also I don't want to use query params. Any suggestions to design this would be great.
When you are making a POST to a service, the parameters you communicate are known as BODY params, they don't go on the query string.
Different technologies have different APIs for interacting with POST params, but the underlying theory is the same, and is described by the W3C HTTP standard
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
The specifics of how to use POST params vary depending on the language and technology you're using. For example, if you are using jquery, there are a couple different ways to do it, with with the $.post('url', data, callback) method or with the $.ajax(...) option.
http://api.jquery.com/jquery.post/
http://api.jquery.com/jquery.ajax/
When reading POST params on the server, you'll generally access them using some some sort of request object, that will store your parameters in memory for you to access. This is highly dependent of the language and framework you're using, but here are links to some common ones:
NodeJS/express: http://expressjs.com/4x/api.html#request
PHP: http://php.net/manual/en/reserved.variables.post.php
ASP.Net: http://msdn.microsoft.com/en-us/library/system.web.httprequest.params(v=vs.110).aspx
Java/Spring: https://spring.io/guides/gs/handling-form-submission/
It should be either part of the context (you can pass it through header) or part of the game object. I prefer the context option, the httpheader can contain some auth bearer token so that you can figure out the user on the backend through the token.
Here is an excerpt from an assignment I am currently doing:
Build a dummy app that:
Contains a REST API that operates over a single resource.
Contains a Backbone client that consumes that API and can list, show, create, update, and remove that resource.
My understanding was that the term "consume" implies total coverage of the API's exposed ressources. However, the assignment says "consumes that API and can [CRUD] that resource".
Is that sentence redundant or is my understanding of the term wrong?
(Bonus question: why searching Google for this question returns countless language-specific tutorials for "consuming an API" but none explain what the term actually means?).
To consume an API means to basically use any part of it from your application.
Consuming an API here means creating a client which can send requests to the API that you build.
It appears that you need to create and API which can handle Create, retrieve, update and delete (CRUD) of a resource. For instance if your REST api is to create a blog, your API should handle CRUD functions for the object/resource blogpost.
POST - Create a blog post
GET - Retrieve a blog post
PUT - Update a blog post
DELETE - Delete a blog post.
It is about the direction of the app's interaction with API - it either provides an API, or consumes it, so there are providers and consumers of API, and this is just a less general and ambiguous term than 'using'.
Simply consuming an API means using it in your application.
For, e.g., GET request to https://someapi/Users will give you all the users.
You need to request this URL https://someapi/Users to get all the users and then you can use it into your application.
I always think about Albert Einstein's quote of "If you can’t explain it to a six year old, you don’t understand it yourself." when someone asks a question that you might take for granted due to technical experience you have on a subject.
I think the following medium.com article does an excellent job explaining it: How do you explain API to a 5-year-old?
simply means : using the API.
You can do it with HTTP method (GET, POST, PUT, DELETE..) using something like Postman (Tool) or maybe you have a client app/library that calls these methods implicitly.
Lets consider the following flow to a RESTfull API:
API root
|
v
user list
|
v
user details
|
v
user messages
Suppose I have a client to consume the API, and I want to retrieve messages from a user with ID 42.
From what I've been studying, my client is not supposed to know how to "build" urls, and it should follow the links given by the API.
How should I do to retrieve messages for the user with ID 42?
The only way I can think is "walk" the whole API from it's root to user messages, which doesn't look very pretty or efficient to me.
Eg:
1 - GET / and get the link to the list of users
2 - GET /user/?id=42 and get the link to details of the user with the ID 42
3 - GET /user/42/ and get the link to user 42 list of messages
4 - GET /user/42/messages/ and finally get the user messages
Did I get something wrong? Is this the right way according to Roy's Fielding paper?
Or is it ok to just assume the messages url is "/user/{id}/messages/" and make the request directly?
Use URL templates in your API root. Let the client consume the API root at runtime. It should look for a URL template named something like "user-messages" with the value of "/user/{userid}/messages/". Then let the client substitute "42" for "{userid}" in the template and do a GET on the resulting URL. You can add as many of these URL templates you want for all of the required, often used, use cases.
The difference between this solution and a "classic" web API is the late binding of URLs: the client reads the API root with its templates at runtime - as opposed to compiling the client with the knowledge of the URL templates.
Take a look at the HAL media type for some information about URL templates: http://stateless.co/hal_specification.html
I wrote this piece here some time ago to explain the benefits of hypermedia: http://soabits.blogspot.dk/2013/12/selling-benefits-of-hypermedia.html
I believe what your real concern is should you go about implementing HATEOAS or not. Now as it's an integral part of REST specifications, it is recommended that each entity should have a link to it's child entity that it encompasses. In your case, API ROOT should show list of users with each "user" having a link (/root/users/{id}) to corresponding user's details. And each User details entity will contain a link to the list of "messages" (/root/users/{id}/messages) which, finally, inturn encompass the link to the actual message detail as well (/root/users/{id}/messages/{messageId}). This concept is extremely useful (and thus a part of the specifications) because the client doesn't need to know the url to where your entity is exposed. For example, if your users were on http://users.abc.com/rest/users/{id} but your messages were on http://messages.abc.com/rest/{userId}/messages/{messageId}, the user entity that encompasses the list of "messages" will already have link embedded to point to the right resource on a different server.
Now that being said, I haven't actually seen many REST implementations out there (I must admit I do not have TOO MUCH of an experience, but enough to give an opinion) where HATEOAS is being used widespread. In most cases the resources are almost always on the same server (environment) and the paths to resources are almost always relative to the root url.Thus, it doesn't make sense for the clients to parse out the embedded links from the object when they can generate one by themselves, especially when the client would like to provide access to a resource directly (View the message directly without getting the user entity provided you already know what the messageId is).
In the end, it all depends on how close do you want your REST implementations to that of specifications and what kind of clients are you going to have. My 2 cents would be: if you have time, implement REST with HATEOAS and feel proud about it :). There are libraries out there that will make this implementation (HATEOAS) somewhat transparent to you REST implementation (I believe spring has one, although not very mature. You can look at it here). If you are like me and don't have much time to go that route, I think you can continue with a normal REST implementation without HATEOAS and your clients will still be OK with it (or so I hope!)
Hope this helps!
I found this article about hacking urls: Avoid hackable URLs.
There is a very interesting discussion about the topic of this question in the comments section.
I'm building an API centric web application.
Our frontend will consume the API and after testing our plan is to release the API to the public.
I'm faced however with problems that in a normal MVC application were pretty straight forward but I can't seem to wrap my head around it in a RESTful way.
Take this example for instance:
A company has multiple office sites which point to a specific address
This address can be shared by multiple sites so Company has a one to many relationship with sites and sites has a many to one relationship with Address
When you update an address I'd like to let the user confirm that for that they either want to update the LOCATION (so all companies that share that location through Site will be updated) or they just made a typo and want to create a new Location
How would I go about this in a RESTful way?
I can do a
I first do a GET if there are other companies using that location
Then I give the user a choice either to do POST (create new location) or do a PUT (update location)
In case of POST also create a new Site linking the new location to the Company.
An other example is if what appears a single form for the user will invoke several different backend entities that have to update.
Any examples or ideas?
In REST, you might thing of the remote service as being the database. If you know how to do it in a generic MVC workflow, for fat-client apps it's the same.
You may want to deal with it on a "try default behavior, and raise attention if not possible" way, or with a "check what's possible and then offer possibilities". It's your app, it's your choice.
Personally, I'd go with a "try default and raise error if edge conditions happen". So in this case, assume (in the client) there is no other company with the same address, and use the corresponding endpoint (PUT). If the server detects a possible conflict, then return some error. The client will then prompt to the user what to do, and use whatever endpoint is chosen (POST or PUT, with a flag that enforces the update)