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.
Related
My understanding of REST is simply that a resource needs some means of self-describing itself. My understanding is that this isn't specifically tied to any one protocol (i.e. HTTP) and that there are theoretically numerous ways of achieving this. This is based on an answer to a SO question here: SOAP vs REST (differences) (and unlike the terrible answer to this question: Are Relay and Graphql RESTful?)
Since a GraphQL API is self-describing via introspection, doesn't that mean that GraphQL is RESTful by default since a client can use introspection to figure out how to query it?
While GraphQL is often mentioned as the replacement for REST, both tackle different problems actually.
REST, to start with, is not a protocol but just a style, which, if applied correctly and fully, just decouples clients from servers. A server following the REST principals will therefore provide the client with any information needed to take further steps. A client initially starts without any a-priori knowledge and learns on the fly through issuing requests and processing responses. HATEOAS describes the interaction model a REST architectue should be build upon. It thereby states that a link should be used to request new information which drives its internal flow. On utilizing similar representation to Web forms (HTML) a server can teach a client on needed inputs. Through the affordance of the respective elements a client knows, without any need for external documentation, what to do. I.e. It might find a couple of options to chose one or multiple options from, enter or update some freetext or push some buttons. In HTML forms usually trigger a POST request and send the entered data as application/x-www-form-urlenceded to the server though the form element itself may define something different.
While REST is protocol agnostic, meaning it can be build up ontop of many protocols, HTTP is probably the most prominent one. A common sample for a RESTful client is the Web browser we are all to familiar with. It will start by invoking either a bookmarked URI or invoke one entered in the address bar and progress from there on.
HTTP doesn't specify the representation the request or response has to be sent in but leaves that to clients and servers negotiating them. This helps in decoupling as both client and servers can rely on the common interface (HTTP) and only bind strongly onto the known media types used to exchange data in. A peer not being able to process a document in a certain representation (due to the lack of the respective mime type support) will indicate his other peer via a respective HTTP status code that it does not understand, and therefore can't serve, the requested media-type format. The media type, which is just a human readable documentation of the syntax and the semantics of the data payload, is therefore the most important part in a REST architecture. Even Fielding claimed:
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
A media type teaches a peer how to parse and interpret the received payload and to actually make sense out of it, though plenty of people still confuse REST for a JSON based HTTP API with over-engineered URIs they put to much effort in to give the URI some kind of logical sense when actually neither client nor server will interpret it anyway as they will probably use the link relation name given for the URI.
GraphQL on the other hand is a basically just a query language which gives the client the power to request specific fields and elements it wants to retrieve from the server. It is, loosely speaking, some kind of SQL for the Web, or as Fielding termed it just a Remote Data Access (RDA). It therefore has to have some knowledge of the available data beforehand which couples clients somehow to the server. If the server will rename some of the fields, the client might not be able to retrieve that kind of information further, though I'm not a GraphQL expert.
As stated above, REST is often confused for a JSON based HTTP API that allows to perform queries on directly mapped DB entries/entities. Keep in mind that REST doesn't prohibit this, though its focus is on the decoupling of peers not the retrieval aspect of some Web exposed database entries. As Jim Webber pointed out in a great talk back in 2011 in REST you don't simply expose database tables, you create a domain application protocol which clients will follow along like in a text-based computer game or in a typical Webshop system on the internet.
Especially the linked introspection documentation of GraphQL reminds me of reflection in Java, which couples to the actual class model available. If something along the datamodel changes, how does the GraphQL interaction behave? Is it able to change and adapt? Is a client built for one API able to work with an other API out of the box? All these are basically requirements for a true RESTful client. It basically has to adept to changes in future as the server is free to evolve anytime. It further shouldn't assume certain endpoints returning certain types but use content type negotiation to request a representation it can work upon.
These should give you enough insights to determine for yourself whether GraphQL can be RESTful or not. In my opinion it isn't, but my insights into GraphQL are rather limited, TBH.
Because graphql publishes Metadata about its types, it's entirely plausible (I think) to build a graphql client that could consume any graphql endpoint ...
SOAP did the exact same thing, though it was still an RPC protocol. A client could look up the ...?wsdl information at run-time and then generate a request according to the schema defined in the WSDL dynamically, though what usually happened was that some pre-generated stub-classes were generated based on the WSDL data that got compiled into a specific client. A client dynamically generating a request still needed a routine that defines what message-type to create and what data the message required as input.
While SOAP could potentially define multiple endpoints within a WSDL, in most cases only one was defined though. This endpoint usually only operates on POST requests even when later on (SOAP 1.2) GET would have been possible also.
According to Fielding's thesis
REST uses a resource identifier to identify the particular resource involved in an interaction between components.
, what would be the resource identifier in GraphQL? GraphQL's documentation states that
... In contrast, GraphQL's conceptual model is an entity graph. As a result, entities in GraphQL are not identified by URLs. Instead, a GraphQL server operates on a single URL/endpoint, usually /graphql, and all GraphQL requests for a given service should be directed at this endpoint.
Similar to SOAP, all the request are targeted towards a single endpoint. This has some impact if you consider caching, which is a further constraint REST implies. How are responses cacheable if the URI is the key used to store the response in the cache?
While all of the aggregation stuff and the flexibility may be nice from a consumer perspective, they are, probably, not in line with the constraints of REST, though Fielding himself claimed that REST is not applicable in all situations and that designers should select a style that fits their needs as not every style is the "silver bullet" to each problem. Even Mike Amundsen stated that GraphQL violates at least 3 constraints imposed by the REST architecture, even though GraphQL seems to have changed the default retrieval method from POST to GET since.
Usually, if you aim for long-living APIs that should be free to evolve in future and that has to deal with lots of clients, especially ones not under your direct control, this is when REST starts to shine. Fielding admits that most developers have problems when thinking long-term. For a single frontend-to-backend system or for a tailor-made client interacting with the own API, REST is not the architecture one should probably follow.
Last but not least, in a later tweet Fielding stated
There is no such thing as a REST endpoint. There are resources. A countably infinite set of resources bound only by restrictions on URL length. A client can POST to a REST service to create a resource that is a GraphQL query, and then GET that resource with all benefits of REST…
which I interpret as, don't focus to much on justifying whether GraphQL is REST or not, but think about how you can integrate its benefits into the overall design.
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 answers on what exactly REST is, I came across a post on SOA on stack overflow:
"magine you are developing a web-application and you decide to decouple the functionality from the presentation of the application, because it affords greater freedom.
You create an API and let others implement their own front-ends over it as well. What you just did here is implement an SOA methodology, i.e. using web-services"
As far as I understand, this is saying that SOA is an umbrella term for designing software in such a way that functionality and presentation are separated (is that not MVC?). And that REST is a means of doing that.
What is the functionality, and what is the presentation is this case?
I understand REST as an architecture for designing server side code that creates URI links as included in the HTML on a browser, and that processes stateless server requests. Is this correct? and if so, what is the alternative to this?
What exactly would a server request that isn't stateless be?
Here is the original question:
JSON, REST, SOAP, WSDL, and SOA: How do they all link together
I don't know if my question makes sense, I'm quite confused.
As far as I understand, this is saying that SOA is an umbrella term for designing software in such a way that functionality and presentation are separated
Yes, that is the goal. But SOA implies a particular approach to that goal where the different parts of a system are actually separate programs, communicating over some API. Each of those parts might be in different programming languages, or on physically separate hosts.
(is that not MVC?)
MVC is a way of structuring a single program by breaking up its code into reusable units. But a Model object is only useful if it can be passed around the application, you couldn't run it as a separate program. You could, however, write an MVC program that was one of the components in an SOA system - e.g. consuming an API in a particular way and turning its results into model objects, then passing them to an HTML view.
I understand REST as an architecture for designing server side code that creates URI links as included in the HTML on a browser, and that processes stateless server requests. Is this correct? and if so, what is the alternative to this?
Not quite. REST has nothing to do with HTML, only HTTP: rather than using a wrapper like an XML document which says "I would like you to do action X, here is the input Y" (which is roughly what SOAP does), REST uses the URL and the type of HTTP request (GET, POST, PUT, DELETE) to describe what's needed. It comes with a philosophy that the object of an action (e.g. /user/42) is more central than the specific verb (e.g. ResetPassword)
What exactly would a server request that isn't stateless be?
HTTP itself is a stateless protocol, but that doesn't mean you can't build stateful applications on top of it. For instance, by using cookies, this website is maintaining the state that I'm logged in to credit me for this answer. In many APIs, some form of session identifier is passed with each request so that you can, for instance, build up a basket of items prior to booking. This can simplify the use of the API, but restrict the order in which operations can happen. A RESTful approach might instead let you create any number of baskets and retrieve them at any time, leaving an action such as searching for a product to be truly stateless.
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
I'm sitting reading on some REST with my fellow teammates, we are writing a RoR application that is going to expose some of its functionality to the rest of the world.
My task on this team is to make a ressource that exposes journal reports. If you call
http://root.com/journalreports
You should get all the journalreports from the service. Thats working like a charm, but I'm confused on how to properly make a ressource that exposes a range of journalreports. Should I make it
http://root.com/journalreports?range=1/2/2010;5/2/2010
Or is this illegal when we talk about REST because of the ?range= interference?
What is the most proper way of giving a REST ressource some parameters?
Parameters are perfectly OK, especially for search-resources like in your case (querying a set of journals).
I recently answered similar question (path vs. parameter)
REST doesn't make query parameter "illegal" in any way. It's an architectural style, mainly about driving the application by exchanging representations.
Considering URIs are meant to be opaque, there's no real difference between http://example.com/page/1 and http://example/?page=1 for example, as far as REST is concerned (it ultimately depends on the representations that are sent, but the choice or URI style tends to be an implementation detail).
What matters is how the client are going to find out about the URIs of your reports.
HTML can do this very well with forms and query parameters. Whether your service is for browser consumption or another agent doesn't really matter, you can use the same principles. You could have HTML forms (or equivalent if your client isn't a browser) if you want it to be more flexible or via explicit links on your top page. (You may find it's easier to split the range into two parameters, like "from" and "to", if you want this to be more dynamic.)