I want to ask some questions about the REST call. I am the green for the REST call and I would like to like what is REST call and how to use the URL to send a REST call to the server. Can anyone give me some basic tutorial or link for my to reference?
Besides, if I want to send a REST call to the server, what should I do? Do I need to set something in the URL? or set something in the server? Thank you.
REST is just a software architecture style for exposing resources.
Use HTTP methods explicitly.
Be stateless.
Expose directory structure-like URIs.
Transfer XML, JavaScript Object Notation (JSON), or both.
A typical REST call to return information about customer 34456 could look like:
http://example.com/customer/34456
Have a look at the IBM tutorial for REST web services
REST is somewhat of a revival of old-school HTTP, where the actual HTTP verbs (commands) have semantic meaning. Til recently, apps that wanted to update stuff on the server would supply a form containing an 'action' variable and a bunch of data. The HTTP command would almost always be GET or POST, and would be almost irrelevant. (Though there's almost always been a proscription against using GET for operations that have side effects, in reality a lot of apps don't care about the command used.)
With REST, you might instead PUT /profiles/cHao and send an XML or JSON representation of the profile info. (Or rather, I would -- you would have to update your own profile. :) That'd involve logging in, usually through HTTP's built-in authentication mechanisms.) In the latter case, what you want to do is specified by the URL, and the request body is just the guts of the resource involved.
http://en.wikipedia.org/wiki/Representational_State_Transfer has some details.
Related
We have a series of REST services that pull resources by identifier but we've been recently tasked with passing disclosure parameters to save with audit.
What use to be...
GET entity/{id}
now turns into something like...
GET entity/{id}?requestName=&requestingOrganization=&reasonForUse=&verificationMethod=&otherAuditDisclosureProperties....
The state of entity does not change and is still idempotent however we must audit the additional information with each call in order to provide it.
First thought was to construct a body instead but that did not seem proper for a GET. This is the second approach using query parameters which have no intention of querying/filtering. These additional parameters are truly context information captured at the point of request. These are the equivalent of SAML attributes within a SOAP call that live outside of the SOAP body (which makes me think as possible header attributes).
Also note, that this information is relayed so the authentication token provided is for the service user calling in and not the actual identity of the context. The identity of the original caller is implicitly trusted in the trust framework surrounding.
How would you define this verb/path?
Maybe a custom header: vnd.mycompany.myheader; where you put all the params you need in some parseable format: name1=value1; name2=value2. You take the waste out of the query string.
The off-topic response
I cannot imagine an scenario where you are asking the user of an API for such subjective information, that requires a lot of effort to provide (as it changes per request) and provides no value to the client. It is only for your internal use. The most probable result is clients hard coding those values and repeating them over in all requests.
If the client is internal you may be looking for ways to correlate requests that span multiple services, like Sleuth, which will let you understand why clients are using your API.
If the client is external, think of making surveys and personal interviews with developers. I'd also suggest that you first nurture your API community to reach those people and understand how and why they use your API.
I agree with Daniel Cerecedo. The proper way is to add the information as part of your Request Header.
A general information can be found at: https://www.w3.org/Protocols/HTTP/HTRQ_Headers.html
The implementation will depends on your programming language.
Looking for clear and concise explanations of this concept.
A RESTful application is an application that exposes its state and functionality as a set of resources that the clients can manipulate and conforms to a certain set of principles:
All resources are uniquely addressable, usually through URIs; other addressing can also be used, though.
All resources can be manipulated through a constrained set of well-known actions, usually CRUD (create, read, update, delete), represented most often through the HTTP's POST, GET, PUT and DELETE; it can be a different set or a subset though - for example, some implementations limit that set to read and modify only (GET and PUT) for example
The data for all resources is transferred through any of a constrained number of well-known representations, usually HTML, XML or JSON;
The communication between the client and the application is performed over a stateless protocol that allows for multiple layered intermediaries that can reroute and cache the requests and response packets transparently for the client and the application.
The Wikipedia article pointed by Tim Scott gives more details about the origin of REST, detailed principles, examples and so on.
The best explanation I found is in this REST tutorial.
REST by way of an example:
POST /user
fname=John&lname=Doe&age=25
The server responds:
200 OK
Location: /user/123
In the future, you can then retrieve the user information:
GET /user/123
The server responds:
200 OK
<fname>John</fname><lname>Doe</lname><age>25</age>
To update:
PUT /user/123
fname=Johnny
Frankly, the answer depends on context. REST and RESTful have meanings depending on what language or framework you're using or what you're trying to accomplish. Since you've tagged your question under "web services" I'll answer in the context of RESTful web services, which is still a broad category.
RESTful web services can mean anything from a strict REST interpretation, where all actions are done in a strict "RESTful" manner, to a protocol that is plain XML, meaning its not SOAP or XMLRPC. In the latter case, this is a misnomer: such a REST protocol is really a "plain old XML" (or "POX") protocol. While REST protocols usually use XML and as such are POX protocols, this doesn't necessarily have to be the case, and the inverse is not true (a just because a protocol uses XML doesn't make it RESTful).
Without further ado, a truly RESTful API consists of actions taken on objects, represented by the HTTP method used and the URL of that object. The actions are about the data and not about what the method does. For example, CRUD actions (create, read, update, and delete) can map to a certain set of URLs and actions. Lets say you are interacting with a photo API.
To create a photo, you'd send data via a POST request to /photos. It would let you know where the photo is via the Location header, e.g. /photos/12345
To view a photo, you'd use GET /photos/12345
To update a photo, you'd send data via a PUT request to /photos/12345.
To delete a photo, you'd use DELETE /photos/12345
To get a list of photos, you'd use GET /photos.
Other actions might be implemented, like the ability to copy photos via a COPY request.
In this way, the HTTP method you're using maps directly to the intent of your call, instead of sending the action you wish to take as part of the API. To contrast, a non-RESTful API might use many more URLs and only use the GET and POST actions. So, in this example, you might see:
To create a photo, send a POST to /photos/create
To view a photo, send a GET to /photos/view/12345
To update a photo, send a POST to /photos/update/12345
To delete a photo, send a GET to /photos/delete/12345
To get a list of photos, send a GET to /photos/list
You'll note how in this case the URLs are different and the methods are chosen only out of technical necessity: to send data, you must use a POST, while all other requests use GET.
Just a few points:
RESTFul doesn't depend on the framework you use. It depends on the architectural style it describes. If you don't follow the constraints, you're not RESTful. The constraints are defined in half a page of Chapter 5 of Roy Fielding's document, I encourage you to go and read it.
The identifier is opaque and does not cary any information beyond the identification of a resource. It's a nmae, not input data, just names. as far as the client is concerned, it has no logic or value beyond knowing how to build querystrings from a form tag. If your client builds its own URIs using a schema you've decided up-front, you're not restful.
The use or not use of all the http verbs is not really the constraint, and it's perfectly acceptable to design an architecture that only supports POST.
Caching, high decoupling, lack of session state and layered architecture are the points few talk about but the most important to the success of a RESTful architecture.
If you don't spend most of your time crafting your document format, you're probably not doing REST.
It means using names to identify both commands and parameters.
Instead of names being mere handles or monikers, the name itself contains information. Specifically, information about what is being requested, parameters for the request, etc..
Names are not "roots" but rather actions plus input data.
I've learned the most from reading the articles published on InfoQ.com:
http://www.infoq.com/rest and the RESTful Web Services book (http://oreilly.com/catalog/9780596529260/).
./alex
Disclaimer: I am associated with InfoQ.com, but this recommendation is based on my own learning experience.
I have a question about REST in general.
Imagine I have a WCF webservice that is used to add an operation performed on a bank card.
The problem is that there are about 30 different parameters to pass on the WS.
On WCF that's pretty easy to do, calling a RPC with all those parameters.
The problem is that I wanted to switch this WCF WS to a REST API with ServiceStack.
The problem I encountered is that if i try to create the operation using REST and passing parameters through 'querystring', I have a string that is AWFUL for reading and VERY VERY LONG (?amount=1234&operationID=12& etc.).
I know this way of doing is not good as it's not resource oriented, but does that i mean i should split the creation of that item into SEVERAL steps (I mean, first create using POST then adding new infos/fields using several post ?).
In this situation I can't see clearly the gain with REST.
If you are passing these parameters in a query string I assume you are performing an HTTP GET. In a REST API GET's are generally reserved for getting data back and the only parameters you pass in are to filter your results. If you are performing an operation that changes the state of the system you want to perform a POST or PUT and pass the data in the body of the message as either XML or JSON, not in the query string.
The gain with REST is if you are opening this API up to other as it makes it much more portable to heterogeneous systems and there are some performance benefits. It also opens your API up to being used by clients such as web browsers. But if this API is just for internal use with .NET application that is not run in a browser then you may want to stick with WCF. REST is not the answer for every problem.
I am not sure to understand your question... REST doesn't mean "no payload". On the contrary, REST means "representational state transfer", so the body of HTTP requests (aka "representational state") is essential.
For a lot of reasons, in the case of a bank, resources are usually bank operations. CouchDB's guide has a very nice scenario about that.
In other words, your "parameters" would be the attributes of the resource representation (in JSON, XML or what you want) you would GET, POST, PUT or DELETE.
Can the REST support in CF10 be used to replace the use of URL Rewrite / ModRewrite for SEO-friendly URL? Write a thin layer that defines the GET and POST method, and <cfinclude> in the correct page?
Or would it tax the server too much and better leave it to the web server to deal with?
Once in CFML, it'd be much easier to be version controlled and maintained.
Thanks
If I understand what you are saying (and perhaps I do not) you would create a handler that would intercept a request, parse out the variables, then request the appropriate page via REST? If that's what you have in mind then I'm not sure I follow what you would gain by this. REST (in general) is more of a generic HTTP API for getting at methods - not so much a page / content paradigm (thought I suppose it could be).
If what you are looking for is to use CF as an rewrite SEO URL handler you can do this now. To use an IIS example, you can create a "custom 404" handler - a CFM page - that gets all the requests that are not tied to a specific document. The handler teases out the variables by parsing through the URL, then "includes" the correct cfm Code or page. That sounds a bit like what you want - but it's not really REST.
Perhaps you are thinking of doing some sort of CFHTTP call where you grab the content you need by constructing the query string from the URL. So if someone loads a url like:
blah.com/productid/550
You could write code like so -
<cfhttp
url="http://blah.com/index.cfm?#listfirst(cgi.script_name,'/')#=#listlast(cgi.script_name,'/')#"/>
<cfoutput>#cfhttp.filecontent#</cfoutput>
While this would do the trick you would be better off using cfinclude rather than this approach. An approach like the one above would actually generate an additional thread per request - one thread for the browser's request and another for the cfhttp request.
Finally I would suggest politely that URL Rewrite (in apache or IIS) is more efficient and more "conventional" and therefore probably a better choice in general.
#Henry
REST is not a replacement for the URL rewriting.
First of all the REST URLs have a format.
http://localhost:8500/rest/App_Name/Rest_Path
"rest" part is mandatory. If you want to change "rest" you can change it in the web.xml (Change the URL Mapping).
App_Name is not mandatory. A server can have a default rest application. For default applications you do not need to specify the AppName. For accessing other (non-default) rest applications, you should specify, the AppName. You can make an application default in the Rest Service registration page in the admin.
Rest_Path identifies the CFC and the function in the CFC that needs to be invoked on the HTTP call.
If these URL format is acceptable, then the URL of these formats can be mapped to a specific function in a CFC. When ever an HTTP call is made to the URL, the corresponding CFFunction will be invoked. By using REST, you are accessing a function in the CFC. It is not possible to access a CFC or a CFM directly in this way. But in the function you can implement whatever you want(Like invoking a CFC, Invoking another CFM etc.).
Does this reply answer your question?
Thanks,
Paul
Even if one could do this, I'd say it's co-opting the wrong tool to do the wrong job. URL rewriting is the web server's job, not the CF server's, and the web server will be a hell of a lot better at it than CF will be. CF's REST interface is for building APIs, not for doing URL rewriting.
If one was to want to handle URL rewriting with CF, then using the 404 handler or onMissingTemplate() handler would be a better fit here, would it not? At least you're using a tool intended for the job (if not the best one).
As for version control... an .htaccess file is just a text file, like a CFML file is. I've not looked too closely at IIS's rewrite module, but can it not use a text file to configure / maintain its rewrites? Obviously Apache can, and we use Helicon's ISAPI Rewrite module which uses an mod_rewrite-compatible .htaccess file.
It seems to me like you're trying to make the developer's job easier by using an approach that would penalise the production performance. "Making the developer's life easier" should never be grounds for compromising the production environment (IMO, obviously).
I've tried to read about what RESTful webservices from Wikipedia etc but I must admit I don't get it. There is a film in which Denzell Washington says "explain it to me like I'm a 5 year old". Can someone do that for me regarding RESTful services?
Bonus points if you know the name of the film.
When I first started with REST, I too had some difficulty getting the "big picture", despite all the documentation out there. Anyways, here's my brief take on REST:
REST is an architectural style for building web services.
REST is built on top of HTTP. Your web service exposes Resources in the form of URIs. Your service allows clients to act upon your service using the standard HTTP verbs (GET=read the resource, POST=create the resource, PUT=update the resource, DELETE=delete the resource).
REST has gained significant momentum in the past few years due largely to (a) Its simplicity over other styles like SOAP. (b) The ubiquity of HTTP. Because HTTP is a time-tested standard, most languages have build-in or 3rd-party HTTP support. You cannot say the same thing about SOAP.
Because REST is a style and not a strict protocol/specification, there is lots of room for interpretation. Many public services that call themselves "REST" do not follow the style to the letter.
RESTful services are services that transfer state represntationally, hence the name REpresentational State Transfer. What this actually means is that data is passed in a declarative manner, which is to say, you get what you ask for.
REST is different from SOAP in that it's not a protocol, and there's no formal specification. SOAP was created to simplify data transfer between applications by using a common interface to access functionality remotely. Unfortunately, to work generally, SOAP is quite complicated, and making SOAP requests is not very straight-forward, requiring XML parsing and generation.
Instead, REST relies on Hyper Text Transfer Protocol (HTTP) to do the heavy lifting. Webservers and server scripts are already built around working within HTTP. To make a request using REST is as simple as a URL request, such as visiting a webpage. The API for a RESTful service can reuse any of HTTP's methods and status codes to signal any errors. Instead of accessing data that's stored in a database through fancy queries and special code, RESTful services allow access that's more similar to a standard filesystem.
The key part of RESTful services, is the declarativeness. A request to GET /widgets/109340 is likely going to get you the data for the widget with an id of 109340. I say "likely" because there's no guarantee. It's up to the implementor. The point is that you can glance at the REST request and know what you expect to be returned. With SOAP, it's much harder to tell whether you have a syntax error.
If /widgets/109340 doesn't exist, instead of passing back a message body, with some specific value to state that the content exists, the server can return a 404 Not Found code, and the user will know that the particular ID doesn't exist. If 403 is returned, the user will know that the item exists, but that they don't have permissions to access it. These request response codes are already supported by programs that make URL requests, because they're common to all servers. This makes REST requests much more resilient.
REST is also flexible on the output format, /widgets/109340 could return a JSON object, but there's no reason it can't return binary data, HTML, XML, SVG, Video, or any other data format. A CDN could use a REST API to serve up versioned content which may or may not be stored on the filesystem: GET /jQuery/1.0.0, GET /jQuery/1.7.1, and GET /jQuery/latest are all RESTful requests.
I'm going to assume you understand what Simple Object Access Protocol (SOAP) is