Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 12 months ago.
Improve this question
We have a requirement to develop an API with CRUD operations that supports batch inputs for each of create, read, update and delete operation.
For ex.
Request for "Create" will be an array of [Name and Value]
Response = array of [Name and Value]
Request for "Update" will be an array of [Name and Value] -> Values of each Name are updated here
Response = array of [Name and Value]
Request for "Delete" will be an array of Names
Response = 204 no content
Request for "Read" will be an array of Names
Response = array of [Name and Value]
We will use POST for Create and Update (or PUT?); However to support batch inputs (max array size=100) in the request body for Read and Delete, I think the option is to use POST (instead of GET for read and DELETE for delete). Is there any downside to this approach? Are there guidelines for implementing such batch operations?
If you are trying to communicate operations that aren't worth standardizing, then you should be using POST.
In particular, PUT has a specific meaning in the transfer of documents over a network domain, and you shouldn't be trying to hijack it.
A request body with DELETE is a bad idea. Don't go there - use POST.
A request body with GET is a bad idea. You should either figure out a way to get the information you need into the target URI of the request (ie, each different body you might send is a unique resource) OR you should use POST.
Using POST isn't a great answer, because you hide from the HTTP application the fact that the request semantics are effectively read only; hiding that information reduces the number of intelligent things that general purpose HTTP components can do. POST is still a much better choice than trying to stick a body on GET.
At some point in the future, we expect the working group to produce some standard for new HTTP method aka GET-with-a-body, and that might give you additional options.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 1 year ago.
Improve this question
I'm building a chat app using node.js koa.
the basic rule of chatting room has limit numbers of user joining,(It's PUT request)
I'm struggling upon give appropriate response status code to client side.
I already checked some documents, here is some candidates I found.
400 bad request
422 Unprocessable entity
403 forbidden
In 400 bad request actually it's not a bad request from client. client abide by rules between client-server.
When it comes to 422 Unprocessable entity it looks more sense when data is not exist in database, which is not my case.
If you are familiar with building rest api, I ask you give me some advice.
Status codes are meta data in the transfer of documents over a network domain. They are used to allow general purpose components to correctly interpret, and act upon, the response message.
Which is to say, you need to be thinking about what's going on at the document level, not what things mean in your specialized domain ("HTTP is an application protocol, but it's not your application protocol" -- Webber, 2011).
403 Forbidden is fine.
409 Conflict is also fine.
422 Unprocessible Entity isn't quite right, based on your description. 422 is "That doesn't mean anything to me", not "I can't do that right now".
The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
Problem
I am writing a API standards document for my firm and have been trying out various tools to enhance our API lifeycle, today I have tried out an API definition security validation tool from apisecurity.io,
it highlighted an interesting error with one of my POST operations:
“You have not defined any schemas for responses that should contain a body.” Link:Response schema undefined and references RFC 7231
The API endpoint that was flagged was a POST operation that returned: A 201 status code, a Location header but no body. (Hence the error as the tool is expecting all 200s codes to have a body except for 204)
Research
The RFC7231 Section 6.3.2 states:
The 201 (Created) status code indicates that the request has been
fulfilled and has resulted in one or more new resources being
created. The primary resource created by the request is identified
by either a Location header field in the response or, if no Location
field is received, by the effective request URI.
The 201 response payload typically describes and links to the
resource(s) created. See Section 7.2 for a discussion of the meaning
and purpose of validator header fields, such as ETag and
Last-Modified, in a 201 response.
Also when looking at what RFC7231 Section 4.3.3 defines for POST operations when the operation resulted in a resource being created, it states:
If one or more resources has been created on the origin server as a
result of successfully processing a POST request, the origin server
SHOULD send a 201 (Created) response containing a Location header
field that provides an identifier for the primary resource created
(Section 7.1.2) and a representation that describes the status of the
request while referring to the new resource(s)."
Interpretation
When a POST results in a successful creation of a resource:
HTTP 201 should be returned
Location header should be returned with the URL of the newly created resource
A "representation that describes the status of the request while referring to the new resource"
The top two are neither a surprise but the third one is where I find conflicting guidance from what the standards ask for and what is available as a precedent.
From my research, Google, Paypal, Github and Stripe, all reputable API creators, send a full representation of the newly created resource and not a "representation of the status of the request".
Is the RFC wrong / out of date and the best practice is that we should return the full body?
I would really value input from others who have encountered / debated this or is interested in the conversation.
It might seem a trivial question but I am trying to document the best practice to drive our consistency forward similar to Zalendo (also appear to return the resource unless a 204 is returned but in that case the client doesnt know if the resource was created or if it was updated by the POST)
Question to answer
Is there a standard to follow for response bodies of this type?
The same answer could apply to a PUT or POST getting a 200 response or a PUT getting a 201.
Is the RFC wrong / out of date and the best practice is that we should return the full body? I would really value input from others who have encountered / debated this or is interested in the conversatio
The RFC is, as far as I can tell, fine.
The idea I think you are missing is Content-Location, which is to say that we can use meta data in the response to make clear, in a standardized way, what the representation we are sending back from the server is.
A typical "representation of the status of the action" might look like
201 Created
Location: /api/new-things/12345
Your document can be fetched from /api/new-things/12345
If instead we want to send a representation of the new document (resource) we created, then we need to signal that in the meta data.
201 Created
Location: /api/new-things/12345
Content-Location: /api/new-things/12345
Hi, I'm your new document, which can be fetched from /api/new-things/12345
Roughly - yes, you can just send the representation of the new thing you created on the server, and your bespoke client can understand that. But we also have the problem that general-purpose components need to understand the conversation as well, and as far as they were concerned, we were having a conversation about the target-uri, not about /api/new-things/12345.
The HTTP standard is about describing what is going on using the semantics that are common to all resources and components, not your specific bit of java script talking to your specific URI.
Using the PUT or POST response to return the updated resource representation rather than the status is commonplace and the APIs you listed are good examples of this. I suppose the rationale for this is to offer some convenience for the client developer.
It's not what is described in the HTTP spec (confirmed by the quotes you gave), and doing this limits the richness of the API.
For example an API may accept valid documents that comply with the schema, but perform business rules assessment or trigger a series of events. The response status is there to let the client know what happened and any problems that occur from a business rules perspective. Note that 40x responses are to do with client errors not user errors.
My view is then to provide a status document listing useful information about such processing including
Business rule evaluation status and results (with links)
Events raised
Actions performed in addition to the storage of the document
Transaction ids for tracing and reference
Timestamps for the document and / or version numbers.
Key data items generated or matched such as tags, ids, keys etc that may be of note.
I am not aware of any standard JSON document formats for this (akin to application/problem+json see https://www.rfc-editor.org/rfc/rfc7807), however perhaps one would be useful e.g. application/processing+json to tighten up API responses in this area.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What's the best/restful way to design an API endpoint for checking existence of resources?
For example there is a user database. While new user tries to sign up I want to check if email has been used on-the-fly.
My idea is: POST /user/exists and payload would be something like {"email": "foo#bar.com"}. The response would be either 200 OK or 409 Conflict.
Is this a proper way?
Thanks!
HEAD is the most effecient for existence checks:
HEAD /users/{username}
Request a user's path, and return a 200 if they exist, or a 404 if they don't.
Mind you, you probably don't want to be exposing endpoints that check email addresses. It opens a security and privacy hole. Usernames that are already publicly displayed around a site, like on reddit, could be ok.
I believe the proper way to just check for existence is to use a HEAD verb for whatever resource you would normally get with a GET request.
I recently came across a situation where I wanted to check the existence of a potentially large video file on the server. I didn't want the server to try and start streaming the bytes to any client so I implemented a HEAD response that just returned the headers that the client would receive when doing a GET request for that video.
You can check out the W3 specification here or read this blog post about practical uses of the HEAD verb.
I think this is awesome because you don't have to think about how to form your route any differently from a normal RESTful route in order to check for the existence of any resource, Whether that's a file or a typical resource, like a user or something.
GET /users?email=foo#bar.com
This is a basic search query: find me the users which have the email address specified. Respond with an empty collection if no users exist, or respond with the users which match the condition.
I prefer:
HEAD /users/email/foo#bar.com
Explanation: You are trying to find through all the users someone that are using the e-mail foo#bar.com. I'm assuming here that the e-mail is not the key of your resource and you would like to have some flexibility on your endpoint, because if you need another endpoint to check availability of another information from the user (like username, number, etc) , this approach can fit very well:
HEAD /users/email/foo#bar.com
HEAD /users/username/foobar
HEAD /users/number/56534324
As response, you only need to return 200 (exists, so it's not available) or 404 (not exists, so it's available) as http code response.
You can also use:
HEAD /emails/foo#bar.com
if the HEAD /users/email/foo#bar.com conflict with an existing rest resource, like a GET /users/email/foo#bar.com with a different business rule. As described on Mozilla's documentation:
The HEAD method asks for a response identical to that of a GET request, but without the response body.*.
So, have a GET and HEAD with different rules is not good.
A HEAD /users/foo#bar.com is a good option too if the e-mail is the "key" of the users, because you (probably) have a GET /users/foo#bar.com.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 4 years ago.
Improve this question
Designing an API and looking for some advice.
Here's the actions:
publish : publish the document (POST)
update : update the document (PUT or PATCH)
unpublish : take the document down with the intention of putting it up later (?)
delete : remove the document completely (DELETE)
Any ideas?
Thanks!
Matt
Update and delete are pretty obvious, as you have them.
Do you consider "publish" the same as "create"? "Publish" can mean taking a document you've created and making it publicly visible. One way to think of it is, you can only create a document once, but then you can publish and unpublish it many times.
You might think about the lifecycle of the document, and what you can do with it after "unpublish". It kind of depends on what you want the sequence: "create (publish?) ... unpublish ... publish ... unpublish ... delete" to do. If publish/unpublish don't do anything different than create/delete, then you can just drop them and avoid the complexity altogether.
The purist REST answer is to provide a property in the representation: { ... "published": true ... } and let the client PUT an update to change that state. If that state changes, it triggers whatever processing is needed to publish or unpublish the document.
However, I was on a team that was uncomfortable with that because there can be big implications, publicly and technically, to publishing a document. So they chose instead to treat the operation as a POST "data processing" request (as the HTTP spec provides) and provide a POST URL to "publish" and "unpublish" the document.
There are some other options. Like take POST as the append verb, and provide a "published list" URI that allows you to add a document to the published list, doing any processing that's required:
POST ht_p://.../documents
{ the document }
POST ht_p://.../published-documents
{ id= }
DELETE ht_p://.../published-documents/{id}
DELETE ht_p://.../documents/{id}
edit: broke the prentend URIs because stackoverflow complained. ;)
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
I'm going to have a site where content remains on the site for a period of 15 days and then gets removed.
I don't know too much about SEO, but my concern is about the SEO implications of having "content" indexed by the search engines, and then one day it suddenly goes and leaves a 404.
What is the best thing I can do to cope with content that comes and goes in the most SEO friendly way possible?
The best way will be to respond with HTTP Status Code 410;
from w3c:
The requested resource is no longer available at the server and no
forwarding address is known. This condition is expected to be
considered permanent. Clients with link editing capabilities SHOULD
delete references to the Request-URI after user approval. If the
server does not know, or has no facility to determine, whether or not
the condition is permanent, the status code 404 (Not Found) SHOULD be
used instead. This response is cacheable unless indicated otherwise.
The 410 response is primarily intended to assist the task of web
maintenance by notifying the recipient that the resource is
intentionally unavailable and that the server owners desire that
remote links to that resource be removed. Such an event is common for
limited-time, promotional services and for resources belonging to
individuals no longer working at the server's site. It is not
necessary to mark all permanently unavailable resources as "gone" or
to keep the mark for any length of time -- that is left to the
discretion of the server owner.
more about status codes here
To keep the traffic it may be an option to not delete but archive the old content. So it remains accessible by its old URL but linked at some deeper points in the archive on your site.
If you really want to delete it then it is totally ok to return with 404 or 410. Spiders understand that the resource is not available anymore.
Most search engines use something called a robot.txt file. You can specify which URLs and Paths you want the search engine to ignore. So if all of your content is at www.domain.com/content/* then you can have Google ignore that whole branch of your site.