While doing initial sync with Google's CardDav server I am doing a REPORT request with sync-collection method. In this request I am passing empty sync-token since its the initial sync.
This is as per RFC 6578 (https://www.rfc-editor.org/rfc/rfc6578#section-3.8).
The request body looks like this:
<?xml version="1.0" ?>
<D:sync-collection xmlns:D="DAV:">
<D:sync-token/>
<D:prop>
<D:getetag/>
</D:prop>
</D:sync-collection>
I am expecting a Multi-Status response with etag's of all contacts.
However, google is returning HTTP error 400.
Can anybody if I am doing anything wrong?
Your request is missing the sync-level element as per https://www.rfc-editor.org/rfc/rfc6578#section-6.1
<!ELEMENT sync-collection (sync-token, sync-level, limit?, prop)>
The Google API is not totally clear about whether they do support empty sync token.
Client applications must switch to this mode of operation after the initial sync.
and
Client programs use the sync-token PROPFIND request on the Address Book to obtain the sync-token representing its current state. Client applications must store this value and issue periodic sync-collection REPORT requests to determine changes since the last issued sync-token. Issued tokens are valid for 29 days, and the REPORT response will contain a new sync-token.
so it is well possible that they rejected the request for that reason.
If it is the case, one would do a PROPFIND with Depth:1 asking for the sync-token property as well as the getetag, then do a sync request based on the sync token property retrieved.
Related
The purpose is to not trigger the request more than once at n days (for financial reasons) - the HTTP client should look into the cache to determine whether the response is already available. Will the max-age directive set to n days in the response help (e.g. Cache-Control: public, max-age=604800)?
I know this is available for GET requests with an enableCaching(ttl) option, but can we achieve similar behavior for POST requests?
To resume, my only idea is that if the response comes with an n day max-age directive set, this would force the service which makes the request to make another call after n days, no matter if it's a GET or POST.
Maybe Redis is that what you're looking for
You can request that POST responses get cached, but there are no promises. From [RFC 7231][1]:
Responses to POST requests are only cacheable when they include
explicit freshness information (see Section 4.2.1 of [RFC7234]).
However, POST caching is not widely implemented.
If you control both the server an the client, you can:
For cases where an
origin server wishes the client to be able to cache the result of a
POST in a way that can be reused by a later GET, the origin server
MAY send a 200 (OK) response containing the result and a
Content-Location header field that has the same value as the POST's
effective request URI (Section 3.1.4.2).
Also, note that any cache could clear out your representation at any time, so just because you ask for something to stay cached doesn't mean it will. You're specifying a max age, not a guaranteed age.
[1]: https://www.rfc-editor.org/rfc/rfc7231#section-4.3.3
I am performing a POST to a resource URI. But the success of this operation depends on the responsiveness or accessibility of another related object. If that object is not responsive or inaccessible, the operation needs to return failure. What HTTP code should I choose in this case?
I am currently brainstorming on the following codes, but could not arrive at the right one:
404 NOT FOUND - This represents "not found" for the resource URI, and not a related inaccessible entity.
412 PRECONDITION FAILED - Applicable only for conditional requests with one or more header fields indicating a precondition - I dont need to provide any.
I am not able to find or zero onto a specific HTTP code.
https://greenbytes.de/tech/webdav/rfc7231.html#status.409:
"6.5.8 409 Conflict
The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict."
Lets check the candidates:
404: always an option but as the same request will sometimes fail or success this will create a flickering behavior which is not what a client would expect when getting 404.
412: RFC 2616 says: "The precondition given in one or more of the request-header fields" - this is not the reason for the failure.
417: similar to 412: "The expectation given in an Expect request-header field could not be met by this server"
503: "The server is currently unable to handle the request due to a temporary overloading or maintenance of the server."
Nothing seems to be perfect but I would choose 503 as it represents the temporary problem best and guides the client to do a retry.
Picking the right status code is always tricky. If you return a status code like 404 for example, debugging can become derailed because someone may not be sure if it's because the URL actually doesn't exist or if it's because of some other reason internally.
Usually the caller only needs to know a few things:
Did the endpoint exist? If not, 404 NOT FOUND
Was my request properly formed and did it pass validation? If not, 400 BAD REQUEST
Was my request denied because of improper authentication? If not, 401 or 403 depending on the context (there is a subtle difference)
Did my request fail because of something out of my control? If so, 500 INTERNAL ERROR
Typically I try to separate the response from the service's logic. If you want to be more specific as to exactly what happened (in your example a dependency is not responsive), returning a bit of JSON that describes in more detail what the problem was is would be a more appropriate place for that as opposed to using the http status code to describe a specific error on the service side.
So in your case, I think 500 is the most appropriate. The caller just knows that something went wrong and there's nothing it can do about it, and it can handle that condition however it needs to. If the caller needs to know more about what happened, use a JSON response to convey that.
List of HTTP status codes
1xx Informational
2xx Success
3xx Redirection
4xx Client Error
5xx Server Error
Refer wiki :
103 Checkpoint
Used in the resumable requests proposal to resume aborted PUT or POST requests.
420 Method Failure (Spring Framework)
A deprecated response used by the Spring Framework when a method has failed.
420 Enhance Your Calm (Twitter)
Returned by version 1 of the Twitter Search and Trends API when the client is being rate limited; versions 1.1 and later use the 429 Too Many Requests response code instead.
450 Blocked by Windows Parental Controls (Microsoft)
A Microsoft extension. This error is given when Windows Parental Controls are turned on and are blocking access to the given webpage.
498 Invalid Token (Esri)
Returned by ArcGIS for Server. A code of 498 indicates an expired or otherwise invalid token.
499 Token Required (Esri)
Returned by ArcGIS for Server. A code of 499 indicates that a token is required but was not submitted.
499 Request has been forbidden by antivirus
Produced by some programs such as Wget when a malicious site is intercepted.
509 Bandwidth Limit Exceeded (Apache Web Server/cPanel)
The server has exceeded the bandwidth specified by the server administrator; > this is often used by shared hosting providers to limit the bandwidth of customers.
530 Site is frozen
Used by the Pantheon web platform to indicate a site that has been frozen due to inactivity.
I was thinking 403. From http://www.restapitutorial.com/httpstatuscodes.html:
The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
Edit: Endpoint - POST /users.
The normal HTTP error code for situations like this is 409 Conflict:
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough
information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.
This should be issued in response to a POST or PUT, typically as part of some sort of RESTful API. It should include a useful error message in addition to the status, and the error should be appropriately encoded (e.g. with XML or JSON).
Obscure HTTP errors are less useful in front-end web services. If you are developing a user-facing website, it's preferable to simply deliver an HTML page explaining the problem with a standard 200 OK.
If you are creating a REST API to create accounts, I would expect the request to be something like:
POST /accounts HTTP/1.1
{userid: "someone#example.com", password: "passw0rd!"}
In this case, I guess an appropriate response code would be 409 Conflict with an error description in the body
HTTP/1.1 409 Conflict
{ error: "Account already exists"}
That status code is for an HTTP error, not what you need. Also, it would be very unhelpful as it does not describe the problem at all.
Why not just send:
Username already exists! Please select another.
403 is an ok response in my opinion. 409 and 412 are also possible choices.
I'm trying to figure out what the correct status code to return on different scenarios with a "rest-like" API that I'm working on.
This example is borrowed from another question about syntax type issues in the body, but my question assumes valid syntax throughout.
Let's say I have an endpoint that allows POST'ing purchases in JSON format. It looks like this:
{
"account_number": 45645511,
"upc": "00490000486",
"price": 1.00,
"tax": 0.08
}
What is the appropriate status code if:
the account number does not exist
the account is closed or the
account identified is not the right kind of account
These are all firmly business layer issues that prevent "processing" from occuring, however, one scenario involves something that in a GET would be a 404.
Note that the account number is not in the URL, so is 404 misleading?
Let's take these one at a time. Each of these codes is a signal to your client that the server is functioning correctly, and that something must be changed in the request before it can be successfully carried out.
HTTP 400
The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
400 typically indicates a syntax error; as a user, I should look at the structure of the request before trying again.
HTTP 404
The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
404 is the standard code used when a web server can't match a url path to anything. As a client, I should look at the URL of the request before trying again.
HTTP 422
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.
422 is generally used for content violations. As a user, I should look at the content of my request before trying again.
Now in your case, account number is an identifying number, but is not included in the URL. A 404 would signal to your user that the URL is wrong, not the payload. Stated another way, suppose your url is:
http://www.myservice.net/endpoint
A 404 would indicate to me that no service exists at /endpoint, instead of no account number. No matter what content I submit, the server will not process my request. The fix I should make then would be to look for an error in the URL, instead of the data payload. So to me a 422 would point me in the right direction, unless you begin to include the account number in the URL.
Ultimately these are design preferences, just make sure you communicate them clearly to your users.
If you consider the accounts to be part of the state of the resource (though indirectly) then you might also consider 409 since that state is in conflict with the semantics of the request.
However, 422 is gaining popularity via Ruby on Rails and Dropwizard where it is used to indicate non-syntactic issues with the body. That growing tendency represents a strong signal to a developer using the API that they need to exclude syntax and focus on the body. Developer time is usually the single largest cost your customers will ever incur, so by directing the attention of their developers you will keep them happy.
So 409 is a possible answer, though rather novel, and 422 is the more conventional approach, although obviously RoR and DropWizard are both rather new so these conventions can be said to be changing fast!
I'd say 422 is adequate in your case, but 400 isn't bad if it's consistent with the rest of your API. It's a common convention to use 400 as an umbrella error code when there's something wrong on the client side, but either the error doesn't fit a particular error code, or you don't want to use too many of them.
A 404 is definitely wrong if there's something wrong with the POST payload.
Case 1 : Account number doesn't exist.
This is a standard case for 404.
Case 2 : Account is closed.
This has do with the logic if you keep the account details when you close it.
If you donot keep the account details when the account is closed, you can give 404.
If you keep the account details after it is closed, you must be marking it (like raising some flag) (or whatever logic you have). In this case, Status code 400 with a proper message of why it is failed and possibly remediation will do.
Case 3 : Account identified is not the right kind of account.
403, as the account is not authorised for completing any purchases makes sense to me. If there is no concept like authorised account, 400 with a explanatory message will do. But I would insist to go with 403 in this case.
Actually, in this case 404 sounds good to me.
I am developing RESTful Services to CREATE operations. In my use case, it is enough to tell the clients whether the transaction is success or fail. And if fail, we need to send them back error code.
Is it possible to send only these information back without sending xml response or JSON response. If so, how to do it.
We have existing error code in 5 digits, we wont be changing this for this api. If this is not possible.
Will JSON response better than XML response.? We are accepting XML request.
Requesting your comments.
I'm going to assume this service will be called over HTTP, since that's what most people mean when they say "RESTful service."
Generally speaking, most people map "create" type functionality to POST methods (though you can also do it with PUT).
If you just need to indicate that the record was created, the answer is "None of the above" (i.e., you don't need a response body at all). Usually a 201 Created is returned with a Location header which specifies the URL of the newly-created resource. In theory, you could also return a 204 No Content since you don't need to pass anything other than the status code (though this would be more appropriate for a PUT, otherwise there is no way to communicate to the client the identifier of the newly-created resource).
For failures, usually a 400-series error is returned if the request message is bad (i.e., it's the client's fault) and a 500-series error is returned if a system error occurs when processing (i.e., it's the server's fault). If you need to convey additional information in the response body, consider returning a response that uses a media type of something like application/vnd.error which allows you to express context information about where the error occurred.