0

I've an existing API, which I'm attempting to make more RESTful.

The app involves a Gifter and a Giftee. The Gifter buys something for the Giftee, and sends the link to the gift on whatsapp.

Before creating a user account for the Giftee, I first do some verification by tying the person to a phone number. I've 2 endpoints:

/sendSmsCode 
/verifyUser

First endpoint sends an sms code to the phone number, and second endpoint takes the sms codes and verifies its correct. /verifyUser then returns a session token. This session token is then used to accept the gift and create the user.

Obviously these are not RESTful endpoints. But the user hasn't been created at this stage so I can't do something like /users/{id}/send-sms (which I know wouldn't be too RESTful either given it includes a verb).

Any suggestions?

Mark
  • 4,428
  • 14
  • 60
  • 116
  • Do you really need an id? You are authenticating so url like /users/auth/send-sms should be good right? Phone number could be a query. – Kris Aug 30 '19 at 09:05
  • 1
    I don't think these belongs to user because at the verification step the user might not even exist (ie phone number is invalid, so we don't create a new user). I'd rather go with something like `/verification/sms` with `GET` to issue a code and `POST`/`PUT` to check it. Though, mapping and naming are matter of personal preferences, so I'd suggest you to write down as many variants as you can to come up with and pick the one you like most. – phil_g Aug 30 '19 at 09:14
  • Why do you think that `/sendSmsCode` or `/verifyUser` aren't falid REST endpoints? The spelling in the URI is not of importance to a true REST client. It will determine whether to invoke that URI based on other properties, such as link-relation names or some accompanying text describing the link's content. The URI itself doesn't (probably shouldn't) make sense to the client. Only the server has to know how to segment it to feed its variables and invoke the correct processing logic – Roman Vottner Aug 30 '19 at 12:52

1 Answers1

0

I meant to post a comment, but it's overly long for a comment, so I'm posting it as an answer (although it may not answer your question directly).

Obviously these are not RESTful endpoints.

REST is an architectural style and not a cookbook for designing URIs. It's never enough to stress that REST itself doesn't care about the URI spelling, as long as the URIs comply with the RFC 3986.

To be considered RESTful, an application must follows a set of constraints defined in the chapter 5 of Roy Thomas Fielding's dissertation.

You mention use use a session token in your question. If the session state is kept on the server, than it's not RESTful at all. REST applications are meant to be stateless, where one request contains all required information to be understood by the server, without taking advantage of session state stored on the server.

I can't do something like /users/{id}/send-sms (which I know wouldn't be too RESTful either given it includes a verb).

One important concept of the REST architectural style is the resource and their identifiers.

The URI (or Universal Resource Identifier) is meant to identify a resource rather than expressing the operation over the resources. The operation to be performed over the resource can be expressed by the request method. The request method is the primary source of request semantics, indicating the purpose for which the client has made this request and what is expected by the client as a successful result.

To properly identify resources, it's a natural choice using nouns (as the verb is expressed by the HTTP method). But it's not mandatory to use only nouns. As long as you comply with the REST constraints, you surely can design a RESTful API with some verbs here and there (and possibly use POST for sending data to such endpoints).

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
  • Thanks for this. The session token is a JWT passed in the header. It lives for 5 mins. – Mark Sep 02 '19 at 07:17