We're designing an API for a hand-held application that will be used in a hospital. The Url of the API is something restfull like /foo/bar/238. The response needs to be localized, so we'll use the Accept-Language header. However, some of the meta-data that will be returned by this API call, needs to be dependent on the nursing-unit where the application is used.
Given that the device knows the location, what would be the best way to send this information along with the request:
use a custom header (or a predefined, if such a thing exists)
tag it along in the querystring
something else...
Obviously both (headers, query parameters) would technically work, I think it comes down to personal preference somewhat.
I would argue against headers normally, since they are part of the infrastructure of HTTP, and they usually do not, or should not be part of the content. Also, clients can not really "discover" or "browse" using headers, and that goes against REST.
So, it must be then part of the URI, for example query parameters. This has the advantage, that it can be linked, tested, navigated, cached, etc.
Approach 1
Depending on your requirements, this information doesn't need to be exposed in a header nor in a query parameter.
I understand the users need to be authenticated to access your API. So, it's very likely you have an Authorization header to perform authentication (who the user is) and authorization (what the user can do).
Provided the users know the nursing unit they are working at, you can return the data according to the user who is currently authenticated in your API, without relying on query parameters or headers.
In this approach, you will need to persist in which nursing unit the user is currently working at. When a user moves from one nursing unit to another, just update the user resource with the nursing unit data:
PUT /api/users/me/nursing-unit
Content-Type: application/json
{
"nursing-unit-id": 1
}
Approach 2
If the first approach mentioned above doesn't suit your needs, using a query parameter is still a good approach.
The nursing unit parameter would fit better in a query parameter rather than in a custom header, once the URL should identify the resource itself in a REST API.
Related
I implement a web application (with Python+Django - to the extent that matters). Users can log in normally with username and password, but in addition I want to provide an API which users use to script the interaction with my site.
For the API authentication my plan was to do something like this:
In the database I create table with 'tokens' - i.e. random strings which point to the user database.
The user gets a token string.
For every API call the user passes the token string along with their request
In the API implementation the code:
Verify the token.
Log the correct user in and execute the API function as the user matching the token.
Log the user out again.
Return the result
Does this make sense? On the one hand it seems very simple - on the other hand it feels quite homemade, something I have heard is not recommended when it comes to security related topics?
I would wholeheartedly recommend looking at django-rest-framework
https://www.django-rest-framework.org/
It literally does all of that and more!
Nope, not a sales person, just a developer :)
It handles quite literally any use case you can think of, and I would be happy to discuss at great length any its not suitable for.
It handles:
Authentication
Parsing
Encoding
View or object level permissions
Object serialisation
Object creation
Object deletion
Automatically generated documentation
Several authentication methods, including custom managed methods
And a bunch of other stuff that makes writing API's in Django much easier
All in all it supports most if not all use cases.
EDIT
It is worth noting that there is a very good reason DRF has short lived access tokens. That is because of security.
Let's say a malicious actor gets hold of your short lived access token, thats a lot better than a "long life" one as you described.
It's worth weighing up security and ease of access, security and protecting your users should always paramount.
Futhermore, I would recommend taking a look at DRF Knox, which is recommended in the authentication section of the DRF docs:
https://github.com/James1345/django-rest-knox
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)
A colleague and I were discussing the implementation of our REST API, and he mentioned that in his previous work they never used GET and instead used POST in place of that. His reasoning is that it promotes consistency; the client (a mobile device) does not need to worry about whether a certain API call is POST or GET, it can assume that it's a POST.
As I said this API is used by mobile devices, so the various browser specific differences between GET and POST don't apply (such as caching GET requests and having GET requests in browser history etc).
Does this have warrant? Still seems like bad practice to me. Can anyone explain the benefits of using both GET and POST instead of all POST?
This is not RESTful. One of the principles of REST is the Uniform Interface. One constraint for this principle is Identification of resources:
Individual resources are identified in requests, for example using URIs in web-based REST systems.
In the context of HTTP a resource is identified by a URI:
http://example.com/service/hotel/123/room/456
This URI identifies room 456 in hotel 1234. To interact with this resource, HTTP verbs are used. To get the state of the resource, GET is used. To change it, PUT is used. POST is used if a subresource of the resource is manipulated but how this pattern is used best is still open for discussion.
Proposing to only use POST for every interaction shows a complete lack of knowledge about REST. Most often people don't think "REST" and they don't think "resources" when the propose this. What they do think is Remote Procedure Call (RPC) which can be implemented over HTTP but has nothing do to with REST.
Summary: Don't use POST for everything. Model your resources and use the proper HTTP verbs.
I am in the process of building a RESTful API for my application. There are very few services that are public and the rest require authentication and authorization.
To be clear, my question is NOT about authenticating web services. I have already decided to send an HTTP header with an access token provided by the server. The reasons for this include:
Creating a "session" that can track the user activity
Timeout access tokens after XXX amount of inactivity
Track user behavior patterns for each "session"
So far, this approach is working fine. I am interested in any design guidelines for providing a "Login" service. I don't want to just authenticate a request, but I want to track usage of the web service against a "session".
In addition to "session" tracking, we have requirements that require that we track failed login attempts and take appropriate action after XXX number of failed attempts as well as password expiring and email address verification before authorizing, etc.
Specifically, I am concerned with the best way to design the URI's for this. One option would be:
/api/authentication/login?username=UN&password=PW
That could return the access token to be used in the header for secure service calls. Is this a good approach? Is there a better approach? Is there a better patter to use for naming the URI?
My biggest problem is that the URI is not purely sticking with the "URI's should represent resources" approach. End the end it is probably not a big deal, but I am wondering if there are better ways.
Thanks!
Often, RESTful APIs like to be stateless. That means that the API itself doesn't care about keeping a session, and doesn't.
What you do is authenticate 1 time, and then get a temporary key. That key eventually is no good anymore because the key has information in it about when it will expire.
Also, since these large APIs are built on message queues, they know timestamps for each action. and they can basically keep track of activity.
So, in RESTful API design, you often have scenarios where your URL has resources in it, and then there are all sorts of additional things that need to be set.
A good rule of thumb is to hide the complexity behind your ?. A typical use case of this philosophy is where you have a bunch of filter options on a get request of /some/resource. How is this relevant? Well, if you remember that its not a mortal sin to decorate your resource based API with other stuff occassionally, then you can treat other scenarios similarly when you feel like resourcefulness may be in question, but essentially you still have RPC-ish endpoints that need to exist to make your API fully functional for your needs. Or, of course, you can just arbitrarily set certain HTTP verbs to equal those things.
If you want to extend your resources with additional functionality, try to stick to the resource structure in your base url of the call, and then decorate it with your one-off needs.
Resource: /api/authentication
With modifier: /api/authentication/login
With data: /api/authentication/login?username=UN&password=PW
Its not so bad. But again, if you wanted to go completely restful, you could say something like this (this is pure conjecture, you need to decide these things for yourself):
Get logged in status - GET - /api/authentication/:id
Create / Update logged in status - POST / PUT - /api/authentication(/:id)
Log out - DELETE - /api/authentication/:id
... or you could have omitted the :id route and just hid that information in the body of data appended to the call, aka hiding complexity
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.