Restfull API organising endpoints

Question

I am trying to organise the endpoints of restfull api which we are building. What I have so far is:

GET - /api/members/list

GET - /api/members/:member_id
PUT - /api/members/:member_id
DELETE - /api/members/:member_id
POST - /api/members - add member

POST - /api/member/forgot_password
POST - /api/member/reset_password
POST - /api/member/sign_up - this is same as - POST - /api/members - add member
POST - /api/member/sign_in 
POST - /api/member/validate

POST - /api/member/auth/twitter
POST - /api/member/auth/gplus
POST - /api/member/auth/facebook

The thing is that I am not sure about

POST - /api/members/forgot_password
OR
POST - /api/member/forgot_password

//For register a member to use post over resource
POST - /api/members
OR
//To have endpoit for that
POST - /api/member/sign_up

so the what I understand about restfull concept is to use the request verbs over a resource. But how this apply when we have /api/members resource and I would like to have an endpoint for login a member?

/api/members/sign_in or /api/sign_in or /api/member/sign_in

What do you think "sign in" means in a RESTful API? What auth schema are you using? — Eric Stein, Nov 29 '16 at 18:25
That's the thing, I don't think in a RESTful `sign in` can be considered as resource. It's a more like functional thing, if I am correct. Not really understand what you mean by auth schema, my login works like this: member provides email and password, then JWT is created. I would have login with facebook as well which would work like this: it will require a valid fb access_token then will create JWT same as the sign in function. — Alex, Nov 29 '16 at 20:41

score 1 · Answer 1 · edited May 23 '17 at 12:01

To me, using plural or singular nouns is a matter of teaste.

GET /api/members should reasonably return a collection of members while to get one is perfectly meaningful to use either

GET /api/members/{id} or

GET /api/member/{id}.

So, if your concern about the forgot_password resource was about the plural or the singular form, there isn't a "better way" to go. It's up to you.

For registering a member, I found more appropriate this option

POST /api/members

because you're actually trying to create a new member resource.

As regards your last question, again is a matter of how you're imaging your sign_in resource. Is it meaningful that sign_in is a subresource of members? Before giving an answer, please pay attention to the trap enclosed in the type of resource you're describing. Are you sure you are conceiving the sign_in as a thing rather than an action?

Under this light, I believe that the sign_in resource would be more naturally placed under a different root. However it's worth mentioning that signing in in REST is a bit tricky. Since the srever is not allowed to keep any session, you must be aware that every request must be authenticated (often via token). i don't want to go off topic, maybe you'll want to read this before implementing your sign in mechanism.

Restfull API organising endpoints

1 Answers1