This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
How to version REST URIs
I'm currently writing a REST service and I would like to get some ideas on how my clients can specify the service version when making a request.
For example when I upgrade my REST server to version 2 I don't want calls to break for all clients that have implemented version 1 of my service.
I've seen others add the version in the url or specify the version in the header somewhere.
There may not be a "best" way to implement this but I would appreciate some thoughts on the subject( pro's and con's of each etc...)
Thanks
We do it via separate routes:
http://my.service.com/v1/user/1
http://my.service.com/v2/user/1
In the case of no change between versions, we just map the route to the controller that services the v1 version of the resource.
Yes, this does create multiple URL's for the same resource, and the wonky hardcore REST evanginlists will start crying, but this way makes it easy to manage for you and your users. I find users can't even use request headers to set things like content types nevermind an X-Path or something like that to handle versioning....
If you really want to avoid the duplicate resource issue, you couldpass in a get paramter like version:
http://my.service.com/user/1?version=1
If no version, default to whatever. This is actually fully REST dogmatic, but I think it puts a lot onto your API users.
You could do some kind of user lookup table to route between version if you have a way to map user or api key to version, but this is pretty crazy overhead.
I would recommend versioning via the Accept/Content-Type header. The URIs shouldn't change across versions unless there is a large structural change to the resources themselves. Here is a great explanation: Best practices for API versioning?
Related
I'm trying to figure out what the latest best practice is when it comes to REST APIs and finding an elegant way to "tell" the client what the response will look like. I'm no web expert. But I just recently joined a new team and I've noticed that in the client code, they have hardcoded URI to APIs... and anytime the schema of the return data changes, they have to patch their client code.
Trying to find a way to make things more dynamic by:
introducing patterns to "discover" API servers.
looking into HATEOAS.
More than anything else though, what I'm trying improve is having to change the client code each time the logic on the server changes as far as the body of a GET response.
I've been reading this:
https://www.programmableweb.com/news/rest-api-design-put-type-content-type/2011/11/18
And in particular, the following comments stood out to me: (under the WRML heading)
this media type communicates, directly to clients, distinct and
complementary bits of information regarding the content of a message.
The Web Resource Modeling Language (WRML, www.wrml.org) provides this
"pluggable" media type to give rich web applications direct access to
structural information and format serialization code. The media type's
self-descriptive and pluggable design reduces the need for information
to be communicated out-of-band and then hard-coded by client
developers
Questions
is WRML still a thing? this book that i'm reading is from 2011... and I'm assuming a lot has changed since then.
Can I cheaply build my own inhouse solution where we use the Content-Type or some other header to provide the clients with schema information?
can you point me to an example / sample code where someone is using custom values in Content-Type or other Headers to accomplish something similar?
Or if you have any other suggestions I'm all ears.
Thank you.
I don't know much about WRML, but I would look into:
HATEOAS formats like HAL/HAL Forms and Siren, which are self-describing.
JSON-Schema to describe responses and requests (and yes they can be linked from HATEOAS responses).
If you don't want to go the hypermedia route, OpenAPI and RAML
I've been developing Ketting for the last 5 years and HATEOAS has been nothing short of magic lately as all the tools have been falling into place.
This question already has answers here:
What is RESTful programming?
(34 answers)
Closed 9 years ago.
I have been trying to understand what it means for a application or library or framework to be RESTful? For example, why is it said that bottle or flask is RESTful whereas cgi + wsgiref is not?
Could you please explain with a minimal code example to describe a RESTful application?
REST is an architecture design pattern; you can read more about the sundry details at wikipedia.
The idea is to attach meaning behind HTTP verbs (GET, POST are two you might be familiar with) in order to affect change of data. The API is accessed using endpoints (URLs) that represent a specific entity or entity groups.
In short, here is how its supposed to work:
GET to fetch information about a specific entity.
POST to create new record about a specific entity.
PUT update the information of an existing entity.
DELETE to obviously delete the record of an entity.
Well designed application use HTTP response codes (such as the 200 and the 404 that you are already used to) to indicate the result of an operation against an endpoint.
There is a large amount of material out there on creating RESTful APIs and services, and a healthy debate on how people are doing REST right or wrong. I leave researching these up to you.
Any language that has a HTTP library can be used to expose a REST API for existing data, but there are companies like apigee, mashery and libraries like Google Cloud Endpoints that take care of the menial work for you.
For Python specifically, there are many libraries. One of the most popular ones is Django REST Framework which works with django. There is also Flask-RESTful which uses flask.
There is also this question that discusses more REST frameworks for Python.
That you are asking to “build a RESTful application” shows your confusion. REST is a way to model an interface to an application as a collection of (typically HTTP) resources on the web that respond to standard web verbs in expected fashions (e.g., GET to read, DELETE to destroy, PUT to update). What's more, in a high-quality RESTful interface, the resources link to each other in descriptive ways; the client never needs to invent the names of any resource because it can just follow links (or remember URLs it saw earlier; that's also legitimate). Content negotiation is also A-OK; let the client say what format of representation of the resource is preferred, and let the server provide that if it can.
If an application can act as (or within) a web server while seeing sufficient information about the requests (particularly the method, path and other headers) then it can use that to present a RESTful interface. It has everything it truly needs. Some library stacks make it easier than others by providing more support for the various conventions, but that's just a matter of how much work you have to do yourself as opposed to leveraging that of others.
Alright, so a better title here may have been "Progressive Enhancement with REST in CakePHP", but at least now I'll know you didn't read the question if your answer just refers to the difference between the two ;)
I'm pretty familiar with REST and how to integrate it with CakePHP, but I'm not 100% on board with how to still maintain a conventionally functioning website. Using Router::mapResources sounds like a great idea, but this creates a problem with maintaining the "gracefully degradation" version of the site, because both POST requests to /resource/ AND GET requests for /resource/add will route to the same action (add). Clearly I'll want this action to return a JSON object if they're using the REST api, but if they're using the degraded version of the site (no JS perhaps), it should be a add form, right?
What's the best way to deal with this. Do you route your REST requests to other action names using Router::resourceMap()? Do you do that crazy hack I saw to have the /api/ prefix part of the resourceMap so you can use api_action functions? Do you have the actions handle both REST and conventional requests via checking isAjax()? If so, how do you ensure that you can rely on the browser to properly support the other two request types?
I've searched around quite a bit but haven't found anything about how to keep conventional requests available in Cake along side REST, so if anyone has any advice or experience, I'd love to hear it!
CakePHP uses extension routing as well, via Router::parseExtension() so;
/test/action will render views/test/action.ctp
/test/action.html also
/test/action.json will render views/test/json/action.ctp
/test/action.xml will render views/test/xml/action.ctp
If all views are designed to handle the same data as set by your controller, you'll be able to show a regular HTML form and handle the posted data the same way as you'd handle the AJAX request.
You'll probably might have to add checks if any data is posted/submitted inside the /add, /edit, /delete actions to prevent items being deleted without a form being posted (haven't tested that though, it might be that cake blocks these urls if mapresources is set for the controller)
REST in CakePHP:
http://book.cakephp.org/2.0/en/development/rest.html
(Extension) Routing
http://book.cakephp.org/2.0/en/development/routing.html#file-extensions
I'm, going to write a web app, which should be CRUD accessible from both, the web and native mobile device apps. For the latter i'm definitely committed to a REST API. Is it possible to realize that with Meteor.com ? Would it be an option to use Meteor for just the web and a second REST interface to directly talk to the mongo? Since the meteor client listens for changes in the mongodb this should not cause conflicts, does it?
As of 2015, look at Gadi's answer for the Meteorpedia entry on REST APIs, and at krose's answer comparing REST API packages. Discussion for folding REST APIs into core is on Hackpad. This question is a duplicate of How to expose a RESTful service with Meteor, which has much better answers. -- Dan Dascalescu
Old answer (2012) below.
For adding RESTful methods on top of your data, look into the Collection API written for Meteor:
https://github.com/crazytoad/meteor-collectionapi
As for authentication for accessing the database, take a look at this project:
https://github.com/meteor/meteor/wiki/Getting-started-with-Auth
Both are definitely infantile in development, but you can create a RESTful API and integrate it with a mobile native client pretty easily.
There are a lot of duplicates of this question. I did a full write-on on this in Meteorpedia which I believe covers all issues:
http://www.meteorpedia.com/read/REST_API
The post reviews all 6 options for creating REST interfaces, from highest level (e.g. smart packages that handle everything for you) to lowest level (e.g. writing your own connectHandler).
Additionally the post covers when using a REST interface is the right or wrong thing to do in Meteor, references Meteor REST testing tools, and explains common pitfalls like CORS security issues.
If you are planning to develop a production application, then Meteor is not an option right now. Its under constant change, and there are still many common features it has to support before its ready to use, which will be quite some time.
For your Question, Somebody has already asked and answered the question about support for file uploading in meteor(also contains HTTP handing related information).
How would one handle a file upload with Meteor?
I'm writing client code (desktop/mobile apps) that interact with RESTful web services for a while. I wonder that such services don't allow you to get delta updates.
I currently write an app that notifies you about new issues added to your Redmine. So I need to download all issues again and then compare them with that I downloaded before. That's very bad solution sir, since there may be dozens of issues.
I'd like to know why RESTful web services don't give you an option to download delta updates. Does it contradict the basic idea of RESTful? Or probably the solution is too obvious to document it?
Too domain-specific to document. Any RESTful application would not find it hard to add new resources that you can GET to see deltas, if only they knew that's what their clients wanted. Have you asked the Redmine group for this feature?