I am creating an API, which is going to list me products page by page with given filter conditions.
To give a brief description, it holds a AWS Lambda behind AWS API.
I am not able to decide whether to use GET or POST.
Because querying is considered a GET operation, so this is natural choice. But having a GET operation with JSON body is not very convenient way. So basically, I am left with the choice of putting it in URL.
About POST, I wont be able to use API cache in future if required.
Please suggest the right way.
Use GET.
Many clients do not support the body for GET, use URL params instead of the body. GET can be cached, bookmarked. Also GET is a natural choice as you are not updating any data.
Related
Currently I set up a RESTful API backend using Django and I can list a set of articles by the following GET:
api/articles/
Also, I can get a single article by:
api/article/1/
Each article is owned by a certain user, and one user could have multiple articles of course.
On the frond end side, I present all the articles at loading of the page, and I hope the user who is logged in currently could see the articles that they own in a different style, e.g, outlined by a box, and has a associated "delete" or "edit" button.
This requires me to tell, after the retrieval of the articles, which ones are owned by the current user programmatically. One way of doing this is to check the current user id with the owner id. However I feel this is not a good choice as the user id is the check is done fully on the client side and may be not consistent with the actual server judgement.
Therefore, is there a way, to tell by looking at the response of the GET, (say, let the server return a property "editable=true/false") to get whether the current user could edit(PUT) the resource?
I understand that this could be done at the server side, by attaching such a property manually. However, I am just asking whether there is better/common practice.
I just started learning web development and I am sorry if the question sounds trivial. Thank you!
You can attach propriety manually as you suggested. The advance of this approach is that you dont need any other http request.
Second possibility might be, that your client intentionally request information about endpoint permissions. In this case I would suggest to use OPTIONS HTTP method. You send OPTIONS HTTP request to api/articles/1 and backend returns wanted info. This might be exactly what OPTIONS method and DRF metadata were made for.
http://www.django-rest-framework.org/api-guide/metadata/
I think that this is a very interesting question.
Several options that come to me:
You can add to the GET api/article/1 response a HTTP header with this information i.e. HTTP_METHODS_ALLOWED=PUT,PATH,DELETE. Doing this way helps the API client because it does not need to know anything else. I think that this is not a good approach when more than one entity is returned.
call to OPTIONS api/article/1. Allowed methods for that user on that resource can be returned but notice that, in my opinion, this approach is not very good in terms of performance, because it duplicates the number of requests to the server.
But what if the entity returned also contains information on the owner or it? can, in this case the client know which policy apply and try to figure out it by itself? notice that the policy can be obtained from another endpoint (just one call would be needed) or even with the login response. If your entities do not contain that kind of information, it could be also returned as a HTTP header (like first option above)
What's happened to the ID fields for groups and videos? The Simple API does give you ID's but the new API isn't, though you do get a URL field with what looks like an ID in it.
Seems you only get a url field now? Can that be used as an alternative?
In the v3 API, the IDs have been removed and instead the unique thing for each item is the URI. You should be able to use the whole URI to uniquely identify the items, but the ID shouldn't need to be extracted from them and presents a list of potential pitfalls since that's an unsupported use case.
Depending on your use case, there are different approaches that make sense for this:
If it's for managing your local cache, you can use the URI safely to uniquely identify the response.
If it's for forming subsequent requests, you will likely find them already formed for you in the metadata key for the response (inside either connections or interactions).
For finding the URI from a Vimeo video, we now include the URI inside the oEmbed response.
I am new to REST. I want to know when to use get methods and when to use post methods. In the process of my literature survey I came across this knowledge.
Actually when I searched for HTTP get and post methods, I read that get doesnt encode URL and post encodes the URL
When I searched for rest get and post methods, I read that get method is used to retrieve data from server and post method is to add some data to server.
But I also read that rest is nothing but a convention to use HTTP.
So I feel like some things are contradicting here. Are the methods of HTTP different?
Please clarify. Also any suggestions on when to use get and post methods are welcome
Resource from which i got this information:
https://www.ibm.com/developerworks/webservices/library/ws-ful/
http://www.cs.tut.fi/~jkorpela/forms/methods.html
GET should be used to retrieve a resource. This operation should be idempotent, meaning it should not change any state on the server.
POST should be used to add new information to the server. This is usually performed on a URL that represents a "container" of resources. The POST will add a new resource to this container.
PUT should be used to update an existing resource.
DELETE should be obvious.
You might enjoy reading this: http://tomayko.com/writings/rest-to-my-wife
The portion of your question which has not received any attention as of yet, and which is probably causing some of your confusion, is: "REST is nothing but a convention to use HTTP." Which is an inaccurate way of describing what REST is/does in terms of it using HTTP to manipulate the state of an app. This is officially known as HATEOAS - http://en.wikipedia.org/wiki/HATEOAS and is pretty much the heart of RESTful web services concept.
I have perused the questions asked about this, but I still don't have a definitive answer.
I have an application and would like to build a RESTful API to expose a subset of information. I have three resources:
users
reports
photos
Users have reports and reports have photos. Photos cannot exist outside of reports and reports cannot exist outside of users.
I have designed the following URLs for my requirements
User login, server responds with token which is sent in the header of all API calls
GET example.com/api/
Get user info
GET example.com/api/users/{username}
Get all user reports
GET example.com/api/users/{username}/reports
Get all photos of a report
GET example.com/api/users/{username}/reports/{report_id}/photos
Add a photo
POST example.com/api/users/{username}/reports/{report_id}/photos
Delete a photo
DELETE example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}
Modify photo description
PUT example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}
Questions
Is it good practice to add a resource id in the URL, i.e. resource/id, or should this rather be added as a query parameter?
Is this method of chaining resources, i.e. resource/id/sub-resource/id/etc., acceptable and good or should I put all my resources at the top level and specify its position with query parameters?
Nothing wrong in this design.But this creates long URL which sometime are difficult to understand and the user of the API needs to know the hierarchy.Moreover the consumer of the API need to write more code in little bit non-standard way(Even though it can be done, but will be little messy). Think this from a different perspective
You have three resources and each has its own identity.So if we refactor the above URI's it will looks like below (I am demonstrating only GET)
User Resource:
Get users list
GET example.com/api/users
Get specific user
GET example.com/api/users/{username}
Report Resource:
Get all reports
GET example.com/api/reports
Get a specific report
GET example.com/api/reports/{report_id}
Photo Resources
All Photos
GET example.com/api/photos
Specific Photo
GET example.com/api/photos/{photo_id}
User All Reports
GET example.com/api/reports?username={userName}
Specific report of a user
GET example.com/api/report?username={userName}&report_id={reportId}
User All Photos
GET example.com/api/photos?username={userName}
User All Photos for a report id (You may not need user Name if report_id is unique irrespective of the user, which will further simplify the URI)
GET example.com/api/photos?username={userName}&report_id={reportId}
All photos of a report
GET example.com/api/photos?report_id={reportId}
This simplifies the understanding and more standard code can be written on the consumer side using this approach.
IMHO you are modelling it well.
Regarding 1 I'd rather go with resource/id rather than query param. But one thing you must have in mind when modelling is the cache mechanism by proxy and so on. So do not forget the headers.
I go for query params for filtering and those sorts.
About the login, the credentials should be in the headers, and no specific resource is needed. Just apply per resource security.
I don't see anything wrong with your scheme.
Most frameworks nowadays use a similar standard for specifying url's (like Django).
In my personal opinion, it makes the URL more readable and a bit nicer for the user.
Looking for clear and concise explanations of this concept.
A RESTful application is an application that exposes its state and functionality as a set of resources that the clients can manipulate and conforms to a certain set of principles:
All resources are uniquely addressable, usually through URIs; other addressing can also be used, though.
All resources can be manipulated through a constrained set of well-known actions, usually CRUD (create, read, update, delete), represented most often through the HTTP's POST, GET, PUT and DELETE; it can be a different set or a subset though - for example, some implementations limit that set to read and modify only (GET and PUT) for example
The data for all resources is transferred through any of a constrained number of well-known representations, usually HTML, XML or JSON;
The communication between the client and the application is performed over a stateless protocol that allows for multiple layered intermediaries that can reroute and cache the requests and response packets transparently for the client and the application.
The Wikipedia article pointed by Tim Scott gives more details about the origin of REST, detailed principles, examples and so on.
The best explanation I found is in this REST tutorial.
REST by way of an example:
POST /user
fname=John&lname=Doe&age=25
The server responds:
200 OK
Location: /user/123
In the future, you can then retrieve the user information:
GET /user/123
The server responds:
200 OK
<fname>John</fname><lname>Doe</lname><age>25</age>
To update:
PUT /user/123
fname=Johnny
Frankly, the answer depends on context. REST and RESTful have meanings depending on what language or framework you're using or what you're trying to accomplish. Since you've tagged your question under "web services" I'll answer in the context of RESTful web services, which is still a broad category.
RESTful web services can mean anything from a strict REST interpretation, where all actions are done in a strict "RESTful" manner, to a protocol that is plain XML, meaning its not SOAP or XMLRPC. In the latter case, this is a misnomer: such a REST protocol is really a "plain old XML" (or "POX") protocol. While REST protocols usually use XML and as such are POX protocols, this doesn't necessarily have to be the case, and the inverse is not true (a just because a protocol uses XML doesn't make it RESTful).
Without further ado, a truly RESTful API consists of actions taken on objects, represented by the HTTP method used and the URL of that object. The actions are about the data and not about what the method does. For example, CRUD actions (create, read, update, and delete) can map to a certain set of URLs and actions. Lets say you are interacting with a photo API.
To create a photo, you'd send data via a POST request to /photos. It would let you know where the photo is via the Location header, e.g. /photos/12345
To view a photo, you'd use GET /photos/12345
To update a photo, you'd send data via a PUT request to /photos/12345.
To delete a photo, you'd use DELETE /photos/12345
To get a list of photos, you'd use GET /photos.
Other actions might be implemented, like the ability to copy photos via a COPY request.
In this way, the HTTP method you're using maps directly to the intent of your call, instead of sending the action you wish to take as part of the API. To contrast, a non-RESTful API might use many more URLs and only use the GET and POST actions. So, in this example, you might see:
To create a photo, send a POST to /photos/create
To view a photo, send a GET to /photos/view/12345
To update a photo, send a POST to /photos/update/12345
To delete a photo, send a GET to /photos/delete/12345
To get a list of photos, send a GET to /photos/list
You'll note how in this case the URLs are different and the methods are chosen only out of technical necessity: to send data, you must use a POST, while all other requests use GET.
Just a few points:
RESTFul doesn't depend on the framework you use. It depends on the architectural style it describes. If you don't follow the constraints, you're not RESTful. The constraints are defined in half a page of Chapter 5 of Roy Fielding's document, I encourage you to go and read it.
The identifier is opaque and does not cary any information beyond the identification of a resource. It's a nmae, not input data, just names. as far as the client is concerned, it has no logic or value beyond knowing how to build querystrings from a form tag. If your client builds its own URIs using a schema you've decided up-front, you're not restful.
The use or not use of all the http verbs is not really the constraint, and it's perfectly acceptable to design an architecture that only supports POST.
Caching, high decoupling, lack of session state and layered architecture are the points few talk about but the most important to the success of a RESTful architecture.
If you don't spend most of your time crafting your document format, you're probably not doing REST.
It means using names to identify both commands and parameters.
Instead of names being mere handles or monikers, the name itself contains information. Specifically, information about what is being requested, parameters for the request, etc..
Names are not "roots" but rather actions plus input data.
I've learned the most from reading the articles published on InfoQ.com:
http://www.infoq.com/rest and the RESTful Web Services book (http://oreilly.com/catalog/9780596529260/).
./alex
Disclaimer: I am associated with InfoQ.com, but this recommendation is based on my own learning experience.