REST: Is it considered calm if the API sends back two types of response?
We have a website and we help buyers connect with sellers. We are building an API to allow buyers to click their contact details and return seller details. This is a transaction and entry into our database. We have created the following API:
POST request, url looks like this:
/api/leads
The request body looks like this:
{
"buyermobile": "9999999999",
"stockid": "123"
}
The answer looks like this:
{
"sellermobile" : "8888888888",
"selleraddress": "123 avenue park"
}
We have a new requirement, that is, we need to send back the PDF url (instead of "sellermobile" and "selleraddress"). This PDF URL will contain the seller information if it comes from one of our customers.
We changed the same API, now the request body looks like this:
{
"buyermobile": "9999999999",
"stockid": "123",
"ispdf": true
}
The answer looks like this:
{
"sellerdetailspdf" : "https://example.com/sellerdetails-1.pdf",
}
Is RESTful this? OR should we create a separate API to receive the PDF response?
source to share
I wouldn't fit that way. What happens when you need to add XLS? Are you also adding "isxls" to the request?
Things I would think:
Use mime type for content matching. Send the same request and include in the header Accept
what you expect back - JSON, PDF, etc. In fact, you get a report instead of a link to the report, which may or may not be better.
- or -
Include a link in a typical response.
{
"sellermobile" : "8888888888",
"selleraddress": "123 avenue park",
"_links": {
"seller-details-pdf": "https://example.com/sellerdetails-1.pdf"
}
}
- or -
Support for a request parameter indicating the type of response.
- or -
You have one property that indicates the type of response, not boolean. Much cleaner if you add new answer types.
The first two options have the bonus of not requiring customers to process multiple response types for a single request. It is not prohibited by any specification, but it annoys customers. Try not to annoy the people you want to pay. :)
source to share
Again, the implementation looks good to me, however you could potentially look at a violation of returning a PDF url to another endpoint, perhaps something like api/lead/pdf
this, your request body will be the same for api/lead
all subsequent endpoints in /lead
. Letting your routes and other code handle small portioned tasks instead of a route that handles multiple flags and multiple code routes.
source to share
This looks good to me - the same input type should give the same answer, but in your case you have two different input types: one with and without the ispdf flag. So it agrees with responses to two different response types, one with and without PDF feed.
This is something else you'll want to document, but it is basically the correct implementation.
source to share