RESTful authentication requiring phone number validation
How to handle RESTful authentication when performing authentication with a phone number that needs to be verified?
For example, let's say a user wants to log in. The user would hit the endpoint with a phone number, which would then queue a text message to be sent to that phone number for verification.
In theory, the two endpoints might look like this:
Authentication [POST / users / authentication]
Finds or creates a user using a phone number, returns that user, and places a text message to be sent to the specified phone number (which is delayed).
-
Request (app / json)
{ "phone_number": "4151111111" }
-
Response 200 (application / json)
{ "id": "85165292-8cce-42a3-960a-ffbc7dac987b", "name": "James", "avatar_url": null, "phone_number": 4151111111 }
Group check
The user provides a verification code that was sent in a text message to ensure that the user requesting authentication is valid.
Verification [POST / users / {id} / verification]
-
Request (app / json)
{ "phone_number_verification_code": "1234" }
-
Response 200 (application / json)
{ "id": "85165292-8cce-42a3-960a-ffbc7dac987b", "name": "James", "avatar_url": null, "phone_number": 4151111111, "auth_token": "ff6828134dd6b2d288qcb8f381b0657c" }
What is the idiomatic way to validate this validation in RESTful? Are the verbs correct? Are the endpoint names correct? Did I miss something?
source to share
Some information is missing from the question. Is the resource a "user" already created on the server, and does the phone number only need to be verified?
Assuming "yes. The following diagram looks good to me: -
Authentication
Request
POST /users/<uid>/phones
{
"phone": "4151111111"
}
Response 201 (Created) should be used when adding a new resource. In this case, a new phone number is generated, which must be returned 201.
Read the specs for more information http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5
According to the REST specifications, the POST method must add a sub-resource. And the GET method should list sub-resources under the resource represented by the URI.
Designing according to these REST specs, doing a GET on the same url should probably return a list of phone numbers. This is optional, but it should be the same as in REST semantics. So the GET request / response should be like this
Request
GET /users/<uid>/phones
Reply 200 ok
{
"phones": [
{"phone": "4151111111", "verified": "no"},
{"phone": "xxxxxxxxxx", "verified": "yes"},
…
]
}
For checks
You now have a resource on the server identified by the URI (/ users // phones / 4151111111). It's just not verified. To check this, send a message with a message directly to the resource. Like this
Request
POST /users/<uid>/phones/4151111111
{
"code": "1234"
}
The answer is 200 ok.
Now GET on "phones" will return "checked": "Yes". Like this,
Request
GET /users/<uid>/phones
Reply 200 ok
{
"phones": [
{"phone": "4151111111", "verified": "yes"},
{"phone": "xxxxxxxxxx", "verified": "yes"},
…
]
}
If "users" have not yet been created, you can also use similar semantics for users. Like this.
GET / users
POST / users, with a payload for adding new users. Answer 201 (generated) etc.
Update
If the user exists or is a new user, the request can be without "users" in the url like this,
POST /phones
{
"phone": "4151111111",
"user": "James"
}
The answer may be 201 (created), but we also have to care if the user existed or not. When the phone number is sent, the corresponding user can be searched in the database and based on different conditions, you can return such responses,
Case 1, the user does not exist
HTTP/1.1 200 OK
{
"rel": "/phones/4151111111",
"phone": "4151111111",
"verified": "no"
}
Case 2, user exists but phone is not verified
HTTP/1.1 200 OK
{
"rel": "/phones/4151111111",
"phone": "4151111111",
"verified": "no"
}
Note that the answer is the same in cases 1 and 2. In case 1, the user is created on the server.
Case 3, the user exists and the phone is already verified
HTTP/1.1 200 OK
{
"rel": "/phones/4151111111",
"phone": "4151111111",
"verified": "yes"
}
In case 3, the user already exists and the phone is verified; so the client should send a GET request instead of re-sending the POST with a confirmation code. The client should automatically redirect instead of the user initiating the POST.
Case 4, the phone already exists but is associated with some other user. In this case, a return with an error code or as requested by your application is required.
Submitting a URI in response to RESTful code-on-demand semantics. The client does not need to know before checking it out.
For verification, the client will now POST the code received in the text message to the URI returned in the previous response. Like this,
POST /phones/4151111111
{
"code": "1234"
}
The answer can be 201 (created) when adding a new phone or 200 with the required answer body.
source to share