REST API: Should single API have multiple responsibilities?

Question

We have classified goods website where we do not have login but users can view products listed by other users. To view details of other users, they have to provide their contact details. To verify if user has provided the correct mobile number, we send back OTP code to the number. The API flow looks like:

1. //API to be hit when user fills form to get seller details of particular stock (this expects "stockId" and "mobile" as input):

POST /api/lead/

{
  "stockId": 123,
  "mobile": 9890384328
}

Response of API if "mobile" is already verified (Response code: 200):

{
  "sellerName": "xyz",
  "sellerMobile": "+123232312",
  "sellerAddress": "21, park street, new york"
}

Response if "mobile" is NOT already verified (Response code: 403):

{
   "OTP verification required. OTP is sent to the mobile number."
}

2. User sends back request again with OTP received on mobile to the same lead API:

Request Payload:

{
  "stockId": 123,
  "mobile": 9890384328,
  "otp": 1234
}

It sends back seller details in response if OTP is correct. If OTP provided is not correct, the response is:

{
  "Incorrect OTP."
}

I see few issues in this API design:

1. This API is doing lots of working i.e. returning back seller details, returning back OTP, verifying OTP etc. We can easily break OTP related functionality to some other API. For example one API to generate OTP i.e. GET /api/otp/, other API to verify OTP i.e. POST api/verifyotp/. This would increase number of API calls from client i.e first client will initiate POST lead API, if number is not verified, client will hit OTP API. To verify by OTP it will call verifyOTP api. If it gets verified, it will call leads API to fetch seller details. So, basically it makes 4 API calls vs 2 API calls in above approach.
2. This is non-complaint with HATEOS which suggests "A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server."

Can someone suggest which approach is better?

Answer 1

Simple answer: no.

It is called single responsibility principle for a reason.

Allowing for more than one responsibility in the your public API means that the API "endpoint" has to understand the different responsibilities to "dispatch" to the "correct" implementation for each of these aspects. Or you allow your dual-responsibility API design to corrupt your implementation by having a single thing providing that implementation.

And beyond that: when you have different responsibilities, the range of OK/error return codes simply turns more complicated. That simply makes "everything" harder. For you to write tests - but also for the clients using your API.

In your case, the user does:

• use /api/lead first
• to be told about "not verified"
• use OTP generation API to get the verification code
• to then use a specific OTP API to submit verification code
• to then use /api/lead again