Thanks for looking!
Background
I am building a strictly machine-to-machine web-service (restful) application. The application will listen for requests, retrieve data, construct objects, serialize to JSON and return the JSON object.
This application will ultimately be used by other web applications as well as iOS apps, Android apps, and even desktop apps.
The existing code that I have inherited makes a distinction based on how the service was called in terms of HTTP verbs (GET, POST, etc).
Question
In this day and age of machine-to-machine communication, is the HTTP verb even relevant any longer? Could it in fact be constraining for future adoption of the service API to base the code around HTTP verbs?
Update
fmgp provides a clear answer to "why" these verbs are used, but I feel should I clarify my concern:
Will other platforms such as iOS or Android (for example) be able to originate HTTP verb-based calls like GET and POST? If the answer is "no" then I assume that we should stay away from relying on these verbs and instead build the desired action into the request URL as a parameter.
In RestFul applications, you have a verb foreach CRUD operation:
Create: POST
Read: GET
Update: PUT
Delete: DELETE
Everything claimed "restful" will work the same way according to this philosophy.
There's nothing standard in that, just a clean, good designed, easy to understand programming style. Of course you may want to do all operation with only GET and some query parameters as soon as your client and server can handle it.
Related
I don't exactly know what RESTFUL is. Sure I know it's a mapping of a URL to a resource. But how's that different from an ajax call to a codeigniter URL which echos some JSON?
My application will have subscriptions with states/options, is there any reason I should be using a RESTful setup rather than just some ajax calls when a user switches some of the options for their subscriptions?
You should not necessarily use "pure" REST. If your requirements drive you towards an HTTP-based service returning JSON, then great. But that doesn't imply that you need other aspects of the REST architectural style. You may not need:
An architecture based on resources, in the sense they're defined by the HTTP protocol
A URL structure that maps to resources
You may not want the return result from one request to provide a set of URLs which indicate "where to go" for related requests.
REST is an architectural style, but it can also become a "religion". Be certain that whatever you do is driven by the requirements you need to fulfill, and not based on "ideology".
My team and me are currently working on quite a large project. We are working on an online game, which will be accessible (for the moment), in two ways:
-Via a web browser, an application full JavaScript(client-side), full Ajax (basically meaning that the UI will be managed in JS client side).
-Via an iPhone application (the UI will be managed by the application itself).
Between the two different applications, the core logic remains the same, so I believe (I could be wrong), that the best solution would be to create a web service (if possible using standards such as RESTful or Rest) capable of perming all necessary operations.
Following this logic, I have encountered a problem: the authentication and identity management of the user. This poses problem as the applications users need to be authenticated to preform certain operations.
I’ve looked into WS-security, but this obviously requires passwords to be stored, unencrypted on the server, which is not acceptable!
I then looked into Oauth, but at first glance this seemed like a lot of work to set up and not particularly suited to my needs (the way that applications have to be accepted does not please me since it will be my application and my application only using the web service, not any external application).
I’ve read and heard about a lot of other ways to do what I want, but to be honest, I’m a little confused and I don’t know what information is reliable and what isn’t.
I would like to note that I’m using symfony2 for the backend and jquery for the client side JavaScript.
Furthermore, I would like a detailed, step-by-step response, because I really am confused with all that I have read and heard.
Thank you for your time, and I hope someone can help me as it’s quite urgent.
Good evening
I'm not entirely sure if this answers your request, but since the UI will always be handled on the client side, I think you could use stateless HTTP authentication:
This is the firewall in security.yml:
security:
firewalls:
api:
pattern: ^/api/ # or whatever path you want
http_basic: ~
stateless: true
And then the idea basically is that on the server, you use your normal user providers, encoders and whatnot to achieve maximal security, and on the client, you send the HTTP authentication headers, for example, in jQuery:
$.ajax("...", {
username: "Foo",
password: "bar"
});
Please note that since the authentication is stateless (no cookie is ever created), the headers have to be sent with every request, but, I figure, since the application is almost entirely client-side, this isn't a problem.
You can also check the Symfony2 security manual for further information on how to setup HTTP authentication. Also be sure to force HTTPS access in your ACL, so the requests containing the credentials are secured (requires_channel: https in your ACL definitions).
I just finished reading Restful Web Services and Nobody Understands REST or HTTP and am trying to design an API with a RESTful design.
I've noticed a few patterns in API URI design:
http://api.example.com/users
http://example.com/api/users
http://example.com/users
Assume that these designs properly use Accept and Content-type headers for content negotiations between XHTML, JSON, or any format.
Are these URI's a matter of a pure RESTful implementation vs implicit content negotiation?
My thoughts are that by explicitly using API in the URI is so that a client will expect a data format that is not inherently human pleasing hypermedia and can be more easily consumed without explicitly setting an Accept header. In other words, the API is implying that you expect JSON or XML rather than XHTML.
Is this a matter of separating resource representations
logically on the server side?
The only justification I can come up with for why someone would design their URI's with an API subdomain is because, based off my assumption that this is a scaling technique, it should make routing request load easier in a multi-tiered server infrastructure. Maybe situations exist where reverse proxies are stripping the headers? I don't know. Different servers handling different representations?
Maybe a subdomain is used for external consumers only so that the server avoids the overhead from internal usage. Rate limiting?
Am I missing a point?
My proposed design would attempt to follow RESTful practices by setting appropriate headers, using HTTP verbs appropriately and representing resources in a fashion that I feel including 'API' in the URI would be redundant.
Why would someone design a RESTful API with 'API' in the URI?
Or could they? Maybe my problem with not understanding this design is that it doesn't matter as long as it follows some combination of specification which may not lead to a RESTful API implementation but close? There is more than one way to skin a keyboard cat.
HATEOAS related?
Update: While researching this topic I have come to the conclusion that it's important to consider ideas from REST but not to treat it as a religion. Thus, whether or not to have 'api' in the URI is more of a design decision than a steadfast rule. If you plan to expose your website's API publicly it would be a good idea to use an api subdomain to help deal with the application's logic. I hope that someone will contribute their insight for others to learn from.
I would (and have) done it to separate it from the 'website' infrastructure because it's probably going to have a higher load and require more infrastructure - it's a lot easier to do millions of API calls a day than get that in page views because you have the full load of n sites/companies and their efforts and traction, collectively and even in some cases individually they're going to attract more traffic than you yourself.
This is my understanding and point of view about your question :
Are these URI's a matter of a pure RESTful implementation vs implicit
content negotiation?
No, they are not part of any official documentation (that I know of), and are usually at the developper/team standards discretion. For example, Zend Framework uses some utility classes to detect XHR requests and how responses should be returned. Granted, ZF is not pure RESTful design (or most PHP application as a matter of fact), but it is still possible to write such designs even in PHP.
I have often seen api being used in urls when the returned data expected is indeed not meant to be used as is for display to the end user. However it is usually a design decision and not necessarily an implied standard.
Is this a matter of separating resource representations logically on
the server side?
More or less. For example, when performing a PUT request, for example, the interface does not necessarily need to be entirely refreshed, and often a simple response message is good enough. While this response message is part of the view, it is not the view. So, for example, http://domay.com/users/ would return the interface to manage users (or whatever), http://domain.com/users/api would perform operations and return interface updates (without a page reload).
Am I missing a point?
Weell, no. Since it is a design decision to use or not api in the URL, you're not missing anything here. With the proper headers,
http://domain.com/users/api/get
http://domain.com/users/get
http://domain.com/users/
can all be valid RESTful requests.
Why would someone design a RESTful API with 'API' in the URI?
Simply put, to have an URL naming convention. So that, when looking at a request in logs, documentation, etc. One will understand it's purpose.
Also keep in mind, that most frameworks (django, RoR,...) provide URL-based routing out of the box. You probably need different views for API vs. HTML responses to manage things like authentication, trotting, limits-check and other specific stuff differently.
Putting in place an additional HTTP-Header based routing system to allow, as you say, implicit content negotiation is often not worth the effort.
User-visible webpage URLs are subject to the whims of webmasters, designers, corporate organization, marketing, fashion, technology, etc.
An API, on the other hand, is supposed to remain stable. By using a subdomain you isolate your API from the rest of the website and the changes it is likely to undergo in time.
I see APIs such as PayPal, etc. offering to call their services using NVP or SOAP/WSDL. When using a .NET environment (3.5) using traditional web services (no WCF) which is better and why? I know WSDL lets you drop in the API URL and it generates the wrappers for you. So then why do companies even offer NVP?
There seems to be never-ending confusion in this industry about the different types of web services.
SOAP is a messaging protocol. It has as much in common with REST as an apple has with a lawn tractor. Some of the things you want in a messaging protocol are:
Headers and other non-content "attributes."
Addressing - routing of a message to different servers/recipients based on the headers;
Guaranteed delivery via queuing and other methods;
Encryption, signing, and other security features;
Transactions and orchestrations;
Accurate representation of complex structured data in a single message;
...and so on. This is not an exhaustive list. What WSDL adds to SOAP, primarily, is:
Discoverability via a contract, a form of machine-readable "documentation" that tells consumers exactly what is required in order to send a message and allows proxies to be auto-generated;
Strict, automated schema validation of messages, the same way XSD works for XML.
REST is not a messaging protocol. REST is a system of resources and actions. It is a solid choice for many architectures for several important reasons as outlined by other answers. It also has little to no relevance to "NVP" services like PayPal and flickr.
PayPal's NVP API is not REST. It is an alternative, RPC-like messaging protocol over HTTP POST for clients that don't support or have difficulty supporting SOAP. This isn't my opinion, it's a statement of fact. One of the fields in the NVP is actually METHOD. This is clearly RPC verbiage. Take a look at their API for UpdateRecurringPaymentsProfile and try to tell me that this makes a lick of sense to describe as a "resource". It's not a resource, it's an operation.
In the case of PayPal specifically, the "NVP" (HTTP POST) API is inferior to the SOAP API in almost every way. It is there for consumers who can't use SOAP. If you can use it, you definitely should.
And I'm not necessarily bashing PayPal for this, either. I know a lot of folks have bashed them for not putting together a "proper" RESTful API but that is not what I am getting at. Not every service in the world can be accurately described with REST. PayPal isn't really a resource-based system, it's a transactional system, so I can forgive their architects and developers for not having a perfectly elegant REST architecture. It's debatable perhaps, but it's not black-and-white. It's fine; I'll just use the SOAP system if I need to.
Compare this to, say, the Twitter API. This is a true REST service. Every "operation" you can perform on this API is accurately described as either the retrieval or submission of a particular kind of resource. A resource is a tweet, a status, a user. In this case it literally makes no sense to use a complex SOAP API because you're not really sending messages, you're not performing transactions, you're just asking for specific things, and these things can be described with a single URL. The only difference is that instead of getting an HTML web page back, you're getting some XML or JSON data; the way you request it is exactly the same.
A REST Web Service usually (always?) uses HTTP GET for the retrieval of some resource. And Twitter does exactly this. GET still uses "Name-Value Pairs" - that's the query string, ?q=twitterapi&show_user=true. Those bits after the ? are name-value pairs. And here's a great example of why you would want to use REST over SOAP; you can hook this up to an RSS feed and get streaming updates. I can turn it into a Live Bookmark in Firefox. Or I can download it in JSON format and bind it to something like a jqGrid. The interesting thing is not that the request uses "Name-Value Pairs"; the interesting thing is that it's a simple URL and can be consumed by anything that knows how to request a web page.
So to try and summarize all of what I've said, think of it this way:
Use a REST API (if available) when you want to expose data, or consume or publish it, as a permanent resource.
Use a SOAP API when the system is transactional in nature and/or when you need the advanced features that a complex messaging protocol can offer, such as RM and addressing.
Use an RPC API (which includes just about any API that's modeled entirely around HTTP POST) when there is no SOAP API or when you are unable to use the SOAP API.
Hope that clears up some of the confusion.
I assume that by Name Value Pairs, you mean REST services.
The benefits to REST are primarily ease of development, simplicity and elegance, and lower overhead (which is very important if you are sending and receiving a lot of small messages).
Here are some of the advantages of REST:
REST is more lightweight
Human readable results
Everything is a URI addressable resource
REST services are more easily cached
REST is easier to build (no toolkits are required)
REST is easier to call (HTTP - GET, POST, PUT, DELETE)
NVP is HTTP POST
name=fred
amount=100
code=403
etc
This is the default format from any HTML browser so it's simple to implement for sending data to a web service
I don't think it's a good format for receiving data from web service? JSON or XML would be more suitable
No everyone uses VisualStudio, or has access to automatic wrapper generators, or wants to use such a beast
Many web mashups are coded in Javascript, so using HTTP POST to send data is the simplest way. The return result is a standard HTML response code (200, 403, 500, etc) and/or some JSON
Many service providers offer multiple API's to cater for all customers
I am little bit confused about what really a web service is. You say Amazone web services,etc like that, they offer information. So what is the requirement to be a web url to be a web service ? Let's say I am not much familiar with web development, how could you explain it to me ? But I can get it if you point some ways.
And also little about SOAP and REST basically for someone really new
What is a web service
It is many things. In programming, in generally refers to a web page, that can be called from an application (be it another web page, or desktop app), and the caller will pass in data to it, or receive data from it.
In this sense, it's basically like a 'method' or 'function' in a normal programming language; except you're calling it over the internet.
SOAP
A message format. As discussed above, a web service is a basically a 'method' or 'function'. SOAP is the 'instructions' and 'data' to this method. It will outline data types, and possibly a bunch of data as well. It is an XML format.
REST
REST is the means of implementing an interface to your application but, implementing access control, and other such things, specifically with HTTP Response codes. So you will get a 401: Denied (I think that's the right code), if you don't have access. There are other types of response codes that are useful. It also makes use of other HTTP commands like PUT/HEAD/OPTIONS.
The W3C defines a Web Service as (quoting) :
A Web service is a software system
designed to support interoperable
machine-to-machine interaction over a
network. It has an interface described
in a machine-processable format
(specifically WSDL). Other systems
interact with the Web service in a
manner prescribed by its description
using SOAP-messages, typically
conveyed using HTTP with an XML
serialization in conjunction with
other Web-related standards.
That definition is maybe a bit too restrictive, considering how that term is used nowadays -- I'd probably go with just the first part of that definition, which is quite generalist :
A Web service is a software system
designed to support interoperable
machine-to-machine interaction over a
network.
Wikipedia also has some interesting definitions, like :
In common usage the term refers to
clients and servers that communicate
over the Hypertext Transfer Protocol
(HTTP) protocol used on the Web.
From what I've seen :
A couple of years ago, when we said "web service", we generally meant "SOAP, WSDL, ..."
Now, when we say "web service", we often mean "whatever allows to call something on another server, be it SOAP, REST, ..."
A Web-Service can be considered as a set of methods that enables communication amongst applications irrespective of the application's coding language or framework.
http://acharyashri.com/blog/WebServices.html
Think of Web services as remote APIs (since they are basically just that). You have a method that you want to implement. Let's suppose the method wasn't built by you and resides somewhere else in the world on equipment that you have no control over—how can you go about providing that remote method what it needs in order to get instantiated?
When you find a Web service that you want to include in your application, you must first figure out how to supply the Web service with the parameters it needs in order for it to work. That need also extends a bit further. Even if you know the parameters and types that are required for instantiation, you also need to understand the types that are passed to your application in return. Without these pieces of information, using Web services would prove rather difficult.
Just as there are standard ways to represent data as well as standard ways to move this data over the Internet using Web services, there is a standard way to get a description of the Web service you are interested in consuming. Web Services Description Language (WSDL) is a specification of XML that describes the Web services you are interested in consuming. It's just an interface to describe a web service.