I've built an API which basically forwards HTTP-Requests to a service of mine. The service calls an internal function and sends the answer back.
Both, request and answer, have a body with information.
The problem is that i dont now which HTTP Method i should use, since none of the descriptions really fit my case. Especially because i, strictly speaking, don't have a resource, but rather a service.
The API is already working, i temporarily used POST since it was the closest, but none the less it doesn't really fit completely.
Related
Under which conditions (if any) will the JSON storage API return a 303 or 307 status code?
The error code reference mentions that this may happen, but for these status gives no further details on when this might happen.
In particular, may this happen in response to an object operation?
Background: I'd like to avoid implementing support for redirects in my client if this not needed (to avoid the extra complexity).
When you connect to an HTTPS endpoint, the cloud management system may decided that it wants you to instead connect to a different endpoint. This can be for many different reasons such as load balancing, resource has been moved, the resource is not available via the endpoint requested, etc.
I wrote a C++ SDK for Google, AWS and Azure. Receiving redirects is very common, so make sure that your code handles this correctly.
In particular, may this happen in response to an object operation?
You need to handle redirects for all HTTP operations. It does not matter which API you are calling. For correctly written code, you don't care what the API is, you follow the redirect.
I am designing a game server API that allows a player to spend some game currency to "explore" a region (randomly getting some resource from that region). As this API call deducts player's game currency, it's not idempotent and unsafe, so I can't use GET, PUT, DELETE, leaving only POST. So my design is
POST /regions/:id/explore
Note that the verb/action is part of the URI, instead of in the HTTP method.
Is this API RESTful? If yes, why? if no, what would be a RESTful design for this API?
There's a lot of discussion on whether REST URIs should have verbs or not, but that's merely a fetish. When it comes to URIs, what determines if your API is more or less RESTful isn't their design, but how your client obtains them. If you can't change your URIs anytime you want, it's not RESTful. If your clients are reading URI patterns from documentation and replacing fields like :id with values to build the final URIs to be used, that's not RESTful, it doesn't matter what the content of the URI is. Do some research on HATEOAS for more information on that.
With that part out of the way, POST is the method used for any action that isn't standardized by HTTP, which means you can usually do almost anything you want and still say it's RESTful, as long as it's clearly documented and the URI isn't from out-of-band information. You can guess what a GET, PUT, PATCH or DELETE does based on the HTTP standard, but you can't guess what a POST does.
Just be careful that you don't make your POSTs like an RPC method. For instance, don't do something where the resource the POST is applied to is identified by the payload instead of the URI. In your case, something like:
POST /explore
{"region_id": :id}
This is what's really meant by the mantra to avoid verbs or method names in the URI.
I am used to consuming Web services via a XMLHttpRequest, to retrieve xml or JSON.
Recently, I have been working with SharePoint REST services, which can return a single value (for example 5532, or "Jeff"). I am wondering if there is a more efficient way than XMLHttpRequest to retrieve this single value. For example, would it work if I loaded the REST url via an iframe, then retrieved the iframe content? Or is there any other well established method?
[Edit] By single value, I really mean that the service just returns these characters. This is not even presented in a JSON or xml response.
Any inefficiency in XMLHttpRequest is largely due to the overhead of HTTP, which the iframe approach is going to incur, as well. Furthermore, if the Sharepoint service expects to speak HTTP, you're going to need to speak HTTP. However, an API does not have to run over HTTP to be RESTful, per Roy Fielding, so if the service provided an API over a raw socket -- or if you simply wanted to craft your own slimmer HTTP request -- you could use a Flash socket via a library like: http://code.google.com/p/javascript-as3-socket/. You could cut the request message size down to under 100 bytes, and could pull out the response data trivially.
The jQuery library is a well established framework which you can use. It´s also an article which answer your concrete question at StackOverflow.
I'd like to put some kind of caching reverse proxy in front of a SOAP webservice
over HTTP to improve both performance and availability.
Is there some software that
performs this? (Preferably free and easy to install/use).
The idea is here: the responses of the webservice vary with the request, but
for each request the responses rarely change. So the proxy could
store the responses for each request for some time, and give the cached
response when the same request is sent again. There is only a limited number
of different requests.
The proxy does not need to parse and understand the request or response.
But it does need to understand HTTP POSTs and, say, construct a hash
of the request in order to find the correct response. Caching by the URL,
as done normally in HTTP Proxies, does not help here.
(Of course one can cache the webservice's results in the application
that calls the webservice, but I am looking for a solution that is
standalone, independent from the application.)
Try Ventus Proxy For Webservices. it does exactly what you need.
http://www.ventusproxy.com
I'm not sure if it works with SOAP or not, but check out Varnish. It's a very powerful cache/reverse proxy.
We have HTTP webservices that are RPC. They return XML representing the object the either retrieved or created. I want to know the advantages (if any) of "restifying" the services.
POST http://www.example.com/createDoodad
GET http://www.example.com/getDoodad?id=13
GET http://www.example.com/getWidget?id1=11&id2=45
POST http://www.example.com/createWidget
POST http://www.example.com/createSprocked
One thing I see is that we don't need representations for EVERY resource and we don't need to support all operations (GET, PUT, POST, DELETE) on all resources either.
Basically my question is this.
Convince me that I should be using restful services instead of RPC over HTTP and what would those restful services should be?
For one it's all about semantics, a URI is a Uniform Resource Indicator. HTTP provides methods to GET, POST, PUT, and DELETE a resource. HTTP headers specify in which format I want to recieve or send the information. This is all readily available through the HTTP protocol.
So you could reuse the same URL you use for HTML output to get XML, JSON in a way that HTTP was meant to be used.
XML-RPC and SOAP are based on calling methods that are described by an XSD or WSDL file whilst REST is based on getting/modifying resources. The difference is subtle but apparent. The URL solely describes the resource and not the action as is often the case with SOAP and XML-RPC.
The benefits of REST are that you can utilize HTTP verbs to modify a resource as supposed to a method call that could be named create/new/add, etc. Meaningful HTTP status codes instead of different kinds of error responses and being able to specify different formats on the same resource in a standard way.
You also don't have to accept ALL the verbs on a RESTful resource, for example if you want a read-only resource just return a 405 status code Method Not Allowed on any verb which isn't GET.
Should you redo your RPC calls to REST ? No, I don't think so. The benefits don't outweigh the development time. Should you learn REST when setting up a new Webservice ? Yes, I personally do think so, consuming a REST resource will feel a lot more natural and can grow much more rapidly.
EDIT
Why I feel REST wins over XML-RPC/SOAP is that when developing websites you already aggregate all the neccessary data for the output to HTML, you also write validating code for POST bodies. Why should you change to a different protocol just because the transport markup changes?
This way when you design a new website (language agnostic) if you really think of URI's as resources you basically use your URI's as method calls with the HTTP verb prefixing the method call.
That is, a GET on /products/12 with an HTTP header Accept: application/json; basically (imaginary) translates to getProducts(12,MimeType.Json).
This 'method' then has to do a couple of things
Check if we support JSON as a MIME type. (Validate request)
Validate request data
Aggregate data for product 12.
Format to JSON and return.
If for some reason in the next 4 years YAML is going to be the next big craze and one of your consumers wishes to talk to you in that way this MIME type is plugged in a lot easier than with regular web services.
Now product 12 is a resource you most likely also want to accept HTML MIME types on to display said product, but for a URI like /product/12/reviews/14/ you don't need an HTML counterpart, you just want your consumers to be able to post to that URL to update(PUT)/delete(DELETE) their own review.
In thinking of URIs strictly as resources, not just a location of a web page, and these resources in turn combined with the HTTP request to method invocations on the server side leads to clean (SEO friendly) URLs and (more importantly?) ease of development.
I'm sure there are frameworks in any language that will automatically do the mapping of URIs to method invocations for you. I can't recommend one since I usually roll out my own.
ASP.NET MVC also works on the same principle, but in my opinion it doesn't produce RESTful URIs. ASP.NET MVC makes the verb part of the URI by default having said that it's good to note that by no means does ASP.NET MVC force this (or anything for that matter) upon you.
If you're going to choose a framework at the very least they should:
Bind URI's to methods on the server
Support Object to JSON/XML, etc. serialization. It's a pain if you have to write this yourself although, dependent on the language, not neccessary all too difficult.
Expose some sort of type safe request helpers to help you determine what was requested without parsing the HTTP headers manually.
Try taking the verbs out of your URLs:
POST http://www.example.com/Doodad
GET http://www.example.com/Doodad/13
GET http://www.example.com/Widget/11/45
POST http://www.example.com/Widget
POST http://www.example.com/Sprocked
Query strings shouldn't be used for accessing a resource in a hierarchical, non-query manner. Query strings are usually ignored when caching, which is dangerous and slow.