I have a REST API, and I want to create a method that accepts a username and password, makes sure they're valid, and returns a user resource.
This is NOT to validate users of the REST APIs. The users are part of a separate system, and the API manages them.
What method and URL are appropriate for this?
GET doesn't seem like a good idea, since it would put the password in the query string. Plus this method might update the last-login-date on the user, so it's not idempotent.
I could use PUT, but I use that to update the user. So I could PUT to a different URL, but what would be an appropriate URL for this? Something like /user/credentials might imply that you're updating the credentials, not validating them.
The way I usually handle this is by performing a POST request to e.g. /user/login or simply /login.
You are basically creating a login attempt, therefore POST sounds reasonable, the same way as you can POST a search request.
By doing this you allow yourself to put the login credentials in the POST body, so they're not exposed in the url. And you are not updating the user resource, so you don't have to use PUT.
Example
POST http://example.com/login HTTP/1.1
{
"username": "Jon Skeet",
"password": "SOiscool"
}
You are POSTing the fact that the user needs a "user resource" to use "the separate system". POST is the only verb that is appropriate when a method isn't idempotent.
If "the separate system" is the only imaginable system the user will ever log on to, I'd choose a simple url like /user/login. Otherwise I'd add a path segment for "the user's relation to 'the seperate system'" like /user/theSeperateSystem/login.
Related
Right now I have a REST service which creates a report via a POST:
POST http://myhost/reports
The report however is not persisted, and cannot later on be retrieved via a GET:
GET http://myhost/reports/{id}
Instead I return the report immediately in the response to the POST. Am I violating any REST principle here, e.g. anything a POST creates should always be accessible via a GET, or is this setup OK?
The POST method isn't a synonym to the create in CRUD. The POST method is used for any operation that isn't standardized, so as long as you document what it does, you're not violating REST, no matter what you do.
There's no such REST principle saying "anything a POST creates should always be accessible via a GET". This is a common misunderstanding due to conflating REST with CRUD. Read this answer for some clarification on that.
In informal language, what a POST says to the server is "take this data and apply it to the resource identified by the given URI, following the rules you documented for the resource media type."
No, you are not violating REST. As long as your interface is uniform it is up to you to determine what actions the urls of your API perform.
As part of your documentation you simply need to state which methods are valid for certain resources and which aren't. I really like to use the Twitter API as a good example of "What to do"
Example: Twitter REST API
POST statuses/update
does not create an object available for access at
GET statuses/update/3
The action performed by the POST method might not result in a resource
that can be identified by a URI. In this case, either 200 (OK) or 204
(No Content) is the appropriate response status, depending on whether
or not the response includes an entity that describes the result.
So according to the HTTP standard this is okay.
Not sure if I'm missing something here, but every site on RESTful design states that updates should be done via a PUT request. I've been doing that, but noticed that the parameters are being put in the URL (unlike a POST request) which means they will show in the logs.
So if a user updates their password, the plain text password will show in the log. This doesn't seem right. What is the proper way to do this?
I don't think that it is required for PUT to have params in the URL to consider it as restful.
You should have the following or something similar
HTTPS PUT /users/<userid>/password
Body: {password: abcd}
We have a login REST service:
POST /sessions
When the users password has expired the next thing that must happen is that the client application will present a change dialog window and then change the users password via:
PUT /users/_ID_/password
What is the best way to communicate this intent to the client? At first I wanted to have POST /sessions return See Other (303). But this causes a GET on /users/_ID_/password. I could return a Multiple Choices (300) response which the client does not do an automatic get on, or I could return an OK (200) and tag in the JSON session object returned.
Having a look at the HTTP status code definitions, I'm thinking the following is the best fit:
409 Conflict
The request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where
it is expected that the user might be able to resolve the conflict and
resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict.
Ideally, the response entity would include enough information for the
user or user agent to fix the problem
There is a conflict with the current state of the session resource because the user needs to change their password before being able to create a session. You can return the url to the change password screen in this response so that the client knows where to go to fix the conflict.
At first I wanted to have POST /sessions return See Other (303).
This isn't correct. It would essentially be saying "Don't POST a session here, POST a session over there." You'd be relying on out-of-band information and hard-coded behaviour to recognise that this isn't the case and you should actually POST a new password there instead.
I could return a Multiple Choices (300) response which the client does not do an automatic get on
But you aren't offering multiple choices.
or I could return an OK (200) and tag in the JSON session object returned.
The POST wasn't successful, so you shouldn't respond with 200.
Are you really asking for the "correct REST response" or are you asking how to achieve a particular effect with HTTP? Because it seems you're looking for loopholes rather than the proper design.
If a request comes in and authorisation fails, then respond with 401 Unauthorized and a WWW-Authenticate header. Then use a custom authentication scheme that indicates the user needs to change their password.
im thinking what is the best RESTful way how confirm email and request reseting password. Im only aiming to find correct URI...
confirm email
PUT /users/{userId}/confirmEmail?code=xyz - does not seem much RESTful because of confirmEmail
PUT /users/{userId}/email?confirmedBy=xyz - maybe better? dunno
reset password (similar problem)
PUT /users/{userId}/resetPassword --DATA {email:xyz#xyz.xy} - same thinkin as before
PUT /users/{userId}/password --DATA {state:reseted,resent:xyz#xyz.xy} - hmmm... again Im not sure
are there any better ways in your mind?:-)
If you want your URIs to refer to resources, then call the resource confirmation and POST confirmations to user accounts.
POST /users/{userid}/confirmation
The true RESTful answer is the URL does not matter, you put it in the confirmation e-mail anyway for the recipient to follow. Use whatever is most convenient for your load balancer, reverse proxy, servers, etc.
For convenience you'll end up accepting the confirmation even if it comes in a GET request, because that's what the browsers of flesh-and-bones humans oblivious to Dr Roy T. Fielding et al. send when clicking on a link in an e-mail :-)
Having established it is completely academic, I'd argue you were right to think of PUT, as the client idempotently places evidence of having access to the e-mail. Repeating the request has no further effect.
Considering that he said a reset service for someone who forgot her password, and not a change password service for someone already logged in...
I would use 2 services. 1st to request the reset password mail, and 2nd to set the new password with the token received in the received mail.
For the 1st:
POST baseUrl/passwordReset
Request body
{
"email" : "my#self.com"
}
This could be POST or PUT, but since a mail delivery is not a resource subject to CRUD anyway, let's not be pedantic and use the old POST that was always used in html forms.
Obviously I would control that the same client (ip? browser? ...) doesn't make me send 20K mails in a minute.
Sending the mail to the user doesn't imply that the old password is not valid. That will only happen later in the second request when the new one updates it.
Response 204 (perhaps you should do it even if you don't know that email, because if you return error that means that when you don't return error you are confirming to a stranger that the given email is registered)
For the 2nd:
POST baseUrl/password
Request body
{
"token" : "3D21BA...4F",
"newPassword" : "m%4pW1!O"
}
Where the token is received in the mail. So the mail could have a link to a page including the token, when the page is loaded, the form is filled and submitted, being the token a hidden field that some javascript reads from the URL and puts here.
This is really a resource that you update, so POST. And I don't think it makes sense to have the same URI with 2 verbs for both, because they are not the same resource/entity at all.
Add
By the way, I would make both HTTPS only, and that's why I put all the sensitive information in the body, not URL parameters.
Firstly, I don't think that PUT is the right method for this. PUT broadly means "put this here", where the URL is identifying where the content should be located. You're really asking an existing resource to perform some action, which makes POST more correct.
To answer your direct question, a RESTful URL should identify the resource you want to handle your request. In this case, the resource is either the user, or some password-resetting resource within the user.
My preference would be for a password-resetting resource:
POST /users/{userid}/password-reset
This makes sense from a HTTP point of view, since you could issue a GET on the resource and receive something which indicates how to action a password reset (e.g. a HTML form prompting for the email address of the associated account).
EDIT:
For the purposes of email validation, there are two obvious options. You could either POST to a "confirm email" resource with the email address and confirmation data, to ask the server to process the confirmation, or you can execute a PUT to put the confirmation information on the server:
POST /users/{userid}/confirm-email
or
PUT /users/{userid}/email-confirmation
Here is a RESTful way.
Request
PUT /{userid}/email HTTP/1.1
Content-Type: text/json+confirmation-code
{"activateCode": "23sfgsg3twt3rgsdhgs"}
Response
HTTP/1.1 200 OK
Content-Type: text/json+email-status
{"email": "my-email#address.com", "active": "true"}
No verbs in the URI needed :)
I don't really see anything wrong with having confirmEmail like the 1st example. In the URL you have the key to the user, confirmEmail is the action, and the data with that action is in the query string.
I've recently worked on this, my take was
POST /{base_url}/password
because I was actually creating a new random password and sending it over to the user
and
PUT /{base_url}/confirmation?token=...
Because I am updating the confirmation that was already sent out when the user registered.
I'm designing a public API to my company's data. We want application developers to sign up for an API key so that we can monitor use and overuse.
Since the API is REST, my initial thought is to put this key in a custom header. This is how I've seen Google, Amazon, and Yahoo do it. My boss, on the other hand, thinks the API is easier to use if the key becomes merely a part of the URL, etc. "http://api.domain.tld/longapikey1234/resource". I guess there is something to be said for that, but it violates the principle of the URL as a simple address of what you want, and not how or why you want it.
Would you find it logical to put the key in the URL? Or would you rather not have to manually set HTTP headers if writing a simple javascript frontend to some data?
It should be put in the HTTP Authorization header. The spec is here https://www.rfc-editor.org/rfc/rfc7235
If you want an argument that might appeal to a boss: Think about what a URL is. URLs are public. People copy and paste them. They share them, they put them on advertisements. Nothing prevents someone (knowingly or not) from mailing that URL around for other people to use. If your API key is in that URL, everybody has it.
It is better to use API Key in header, not in URL.
URLs are saved in browser's history if it is tried from browser. It is very rare scenario. But problem comes when the backend server logs all URLs. It might expose the API key.
In two ways, you can use API Key in header
Basic Authorization:
Example from stripe:
curl https://api.stripe.com/v1/charges -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).
Custom Header
curl -H "X-API-KEY: 6fa741de1bdd1d91830ba" https://api.mydomain.com/v1/users
passing api key in parameters makes it difficult for clients to keep their APIkeys secret, they tend to leak keys on a regular basis.
A better approach is to pass it in header of request url.you can set user-key header in your code .
For testing your request Url you can use Postman app in google chrome by setting user-key header to your api-key.
I would not put the key in the url, as it does violate this loose 'standard' that is REST. However, if you did, I would place it in the 'user' portion of the url.
eg: http://me#example.com/myresource/myid
This way it can also be passed as headers with basic-auth.