My idea is to treat URI's in my rest api as a unique resource, except in the context of the client's location, which is stored in a cookie. Are there any downsides to this approach?
From a philosophical perspective, it's not really REST if you don't uniquely identify the resource via URL (at least, per my reading of Fielding).
From a practical perspective -- and this is based on experience -- you're in for a world of pain if you require web service calls to use cookies. Primarily because it's a piece of information that has to be managed on a different code path, making your client-side code more complex. You'll also run into issues with domain and proxies (particularly if you share the cookie between the service and a traditional web-app), and it isn't portable between clients.
If you're looking to generate different content based on location, why not use a geolocation service?
Edit: why not make location part of the request URL? You can still use a cookie to store this information, and retrieve it using JavaScript. This would leave your service interface clean, and allow you to easily use the service from other clients.
As an API, you should aim at making ease of use for the client programmer a high priority. In many libraries that support HTTP, putting cookies into the HTTP request is more difficult than putting, say, a query parameter into the URL.
I'd be concerned about caching. Do one request with the user at location A, it gets cached, user moves to B and makes the request again, gets location A version of the request.
Related
My app is a Personal Assistant who's main job is to redirect the user to something that complies with his/her wishes. I realize, for example that AllRecipies.com has no API. My question is that can I, say open the browser app with the url as
http://allrecipes.com/search/results/?wt=QUERY>&sort=re.
Is this considered as using their API? Not just AllRecipies, but numerous other such services. If I am using this method, then do I have to request API key, etc? I am not retrieving anything. I am simply redirecting the user to their page with the query pre-written. Does this require all the licensing fees, API Key, etc?
Do I have to agree to this fees(If they ask), Request API Key, etc?
With the particular URL in question, it is simply an HTML web server URL, rather than a web API, as such. You can still get data out of it, but you'd have to parse the HTML yourself to extract what you want from the HTML response.
They may have an API that you can use to access data more directly as JSON, XML, etc, but you'll have to look into that yourself. And you will possibly require an API key to access it. But perhaps not, if it's publicly available and they don't care how many calls they get to it by anonymous users.
You may find this resource useful. It contains a lot of open APIs and code snippets to access them: http://www.programmableweb.com/
If you are simply trying to hit a URL or directing a user to this particular URL which you already know and is static meaning you always hit the same url without change in parameters, then this is not considered an API call and will not be requiring any API key.
However, if they have some APIs exposed, you will need to go through their documentation and using this API most likely requires the use of an API key(alhough this might not be true always). Usually, most platforms have a bunch of APIs available for different scenarios and these are called based on user specific parameters and requirements.
I am trying to create a REST API for my web service.
I want to make the users of the API able to initiate a new request with my service. This involves uploading one or two zip files along with some other parameters.
How can I make this all combined into one request? Or is it better to do it multiple requests somehow?
I don't have a lot of familiarity with making REST APIs so I don't know how people usually do it.
I'm using PHP for my site if that matters.
To do this, you'd need your client to upload in mime/multipart format. I don't know PHP, but I'm sure there's a library out there that will support receiving/parsing the multipart messages you get.
As for whether it's a good idea .. If initiating the request is the creation of a single resource, it's not unreasonable to accept mime/multipart. If the parts being sent are themselves full-fledged resources, it would probably be better to make the client send them up separately, and reference them in the initiation request. Also note that mime/multipart is going to be a bit harder for your clients to deal with than simple requests.
This post seems to be related to what you're trying to accomplish.
Every resource online I have been able to find on the subject of restful api uri only covers standards and practices. But how does one develop a restful uri? This entire time I have developed web pages with extensions. How does one make a page without extensions? I am very confused.
Restful APIs are generally served by URL rewriting or forwarding; the 'pages' are not exactly pages but requests to a service. So something like this:
myco.com/people/jonny/house
Would be the resource for Jonny's house. But there is no page as such, just a service that sees that and either directly calls requestPerson('jonny').house or perhaps rewrites it as a page request that can be fulfilled.
Try to see it less as a file location and more as a request string, so it is more like myco.com/people, which is being asked for 'jonny/house'.
The two things to do when developing a RESTful interface are to decide on your data structure and decide on your request structure/mapping. So you have people and cars, and you permit requests for people, cars, or both. To some degree it is like querying a database via stored procedures; the procedures have to be set up to respond to queries, and they will do so in a predictable manner. The difference is that there is an engine managing the requests and responses, and the responses are generally in html format (though they can be JSON, XML, etc).
I have a website that revolves around transactions between two users. Each user needs to agree to the same terms. If I want an API so other websites can implement this into their own website, then I want to make sure that the other websites cannot mess with the process by including more fields in between or things that are irrelevant to my application. Is this possible?
If I was to implement such a thing, I would allow other websites to use tokens/URLs/widgets that would link them to my website. So, for example, website X wants to use my service to agree user A and B on the same terms. Their page will have an embedded form/frame which would be generated from my website and user B will also receive an email with link to my website's page (or a page of website X with a form/frame generated from my server).
Consider how different sites use eBay to enable users to pay. You buy everything on the site but when you are paying, either you are taken to ebay page and come back after payment, or the website has a small form/frame that is directly linked to ebay.
But this is my solution, one way of doing it. Hope this helps.
It depends on how your API is implemented. It takes considerably more work, thought, and engineering to build an API that can literally take any kind of data or to build an API that can take additional, named, key/value pairs as fields.
If you have implemented your API in this manner, then it's quite possible that users of this API could use it to extend functionality or build something slightly different by passing in additional data.
However, if your API is built to where specific values must be passed and these fields are required, then it becomes much more difficult for your API to be used in a manner that differs from what you originally intended.
For example, Google has many different API's for different purposes, and each API has a very specific number of required parameters that a developer must use in order to make a successful HTTP request. While the goal of these API's are to allow developers to extend functionality, they do allow access to only very specific pieces of data.
Lastly, you can use authentication to prevent unauthorized access to your API. The specific implementation details depend largely on the platform you're working with as well as how the API will be used. For instance, if users must login to use services provided by your API, then a form of OAuth may suffice. However, if other servers will consume your API, then the authorization will have to take place in the HTTP headers.
For more information on API best practices, see 7 Rules of Thumb When You Build an API, and a slideshow from a Google Engineer titled How to Design a Good API and Why That Matters.
What things should a developer designing and implementing an API for a community based website know before starting the heavy coding? There are a bunch of APIs out there like Twitter API, Facebook API, Flickr API, etc which are all good examples. But how would you build your own API?
What technologies would you use? I think it's a good idea to use REST-like interface so that the API is accessible from different platforms/clients/browsers/command line tools (like curl). Am I right? I know that all the principles of web development should be met like caching, availability, scalability, security, protection against potential DOS attacks, validation, etc. And when it comes to APIs some of the most important things are backward compatibility and documentation. Am I missing something?
On the other hand, thinking from user's point of view (I mean the developer who is going to use your API), what would you look for in an API? Good documentation? Lots of code samples?
This question was inspired by Joel Coehoorn's question "What should a developer know before building a public web site?".
This question is a community wiki, so I hope you will help me put in one place all the things that should be addressed when building an API for a community based website.
If you really want to define a REST api, then do the following:
forget all technology issues other than HTTP and media types.
Identify the major use cases where a client will interact with the API
Write client code that perform those "use cases" against a hypothetical HTTP server. The only information that client should start with is the response from a GET request to the root API url. The client should identify the media-type of the response from the HTTP content-type header and it should parse the response. That response should contain links to other resources that allow the client to perform all of the APIs required operations.
When creating a REST api it is easier to think of it as a "user interface" for a machine rather than exposing an object model or process model. Imagine the machine navigating the api programmatically by retrieving a response, following a link, processing the response and following the next link. The client should never construct a URL based on its knowledge of how the server organizes resources.
How those links are formatted and identified is critical. The most important decision you will make in defining a REST API is your choice of media types. You either need to find standard ways of representing that link information (think Atom, microformats, atom link-relations, Html5 link relations) or if you have specialized needs and you don't need really wide reach to many clients, then you could create your own media-types.
Document how those media types are structured and what links/link-relations they may contain. Specific information about media types is critical to the client. Having a server return Content-Type:application/xml is useless to a client if it wants to do anything more than parse the response. The client cannot know what is contained in a response of type application/xml. Some people do believe you can use XML schema to define this but there are several disadvantages to this and it violates the REST "self-descriptive message" constraint.
Remember that what the URL looks like has absolutely no bearing on how the client should operate. The only exception to this, is that a media type may specify the use of templated URIs and may define parameters of those templates. The structure of the URL will become significant when it comes to choosing a server side framework. The server controls the URL structure, the client should not care. However, do not let the server side framework dictate how the client interacts with the API and be very cautious about choosing a framework that requires you to change your API. HTTP should be the only constraint regarding the client/server interaction.