I'm new to REST. I think I'm understanding most of it. However, whether a particular style of URL has anything to do with REST is still confusing. Part of what I read on the web talks about the URL style and in other sources I have seen it argued that the URL style has absolutely nothing to do with REST. So what's the correct answer? And if the answer is that the URL style has nothing to do with it, then why do so many frameworks that "support" REST enforce (or at least support) one style of URL? I would just like to put this issue to rest (bad pun intended).
I think that there is no strict rules that require some fixed URL style. And you can use diferrent styles. But will be better if you use characters of lower case with meaningful words that will at least give some ideas about operation that it performs.
Related
I'm in the process of designing the API layer of one of the research and development applications my company is building. The purpose of the API is to share data from a database and to provide calculation functionalities on our data.
My idea is to build Controller endpoints that follow the classic pattern resources nouns and rest verbs:
GET /api/v1/{organisations}
GET /api/v1/{organisations}/{id}
GET /api/v1/{organisations}/{id}/{offices}
etc.
The developer who's handing me the project strongly suggested that I don't use this convention, he said that companies are moving away from this convention as it is too verbose and, hence, not efficient.
He is suggesting adopting less structured endpoints. Something like this, from the code:
GET /api/v1/{taxEnvId}/covers
GET /api/v1/{coverId}/occupclasses
for example, where the first url could be anything.
I objected saying that it shouldn't change much in terms of efficiency and that the advantages in terms of self-documentation with the design I'm suggesting would be greater than the (in my opinion) very small inefficiency (in terms of bytes sent per request) introduced by a longer path.
He is much more experienced than I am, so I'm wondering whether I am making a mistake in my current 'design'.
Is the classic verb - nouns rest name convention wrong?
Are there any disadvantages I can't see in using that convention?
Is he right stressing on that convention being inefficient?
I couldn't find anyone complaining about that convention on the internet and I'd be happy to listen to other opinions or even redirection to books and links that make my evaluation of this part of the design better.
IMHO your approach seems cleaner and more understandable.
An API must be intuitive and easy to use.
Some links that may work for you:
RESTful Resource Naming
Introduction to REST Endpoints
Best Practices for Designing a Pragmatic RESTful API
Twitter REST API Reference Documentation
I objected saying that it shouldn't change much in terms of efficiency
Since the change is not that different then is it worth arguing over? If he is a senior engineer and the organization wants to try a smaller path approach, then this is an opportunity to help the organization accomplish this goal. If in the end their change to less verbose URL paths leads to no improvement, you can rest assured that you helped arrive to that conclusion. You gotta pick your battles and both URL's look very similar, not really worth arguing if in the end of the day it comes down to opinion, especially when the team already expressed an interest to make the URL paths less verbose.
If you (the company) provides not just data but also functionality in your API, then Rest is a good way to go. Otherwise GraphQL could be a thing, both are fundamentally different.
In short: GraphQL shines if you don't offer buisiness logic.
What I would argue about your approach is the /v1, because that isn't a resource. Versioning is topic on its own.
I find it not very efficient adopting this:
GET /api/v1/{taxEnvId}/covers
GET /api/v1/{coverId}/occupclasses
Just imagine the backing controller. The more types the API has, the more cluttered this controller will become. If that happens, how could this be more efficient or efficient at all?
The urls are short, but urls are cheap.
If he is arguing on bytes being send, introduce him to gzip-compression.
I am choosing a Scala web framework. Among frameworks I am considering are Play, Scalatra and Lift. In the project I am preparing for, security is important. However, web security is a blurry subject for me, and I would like my framework to handle it to a reasonable extent. I seem to be drawn to Play.
I am not asking what is the most secure framework (according to ads – Lift), but, rather, do Scala frameworks handle security for me, and how do they compare in that respect? I don't want to solely rely on my knowledge to make the web-app secure.
I'd vote for Liftweb http://seventhings.liftweb.net/security
The major difference to other frameworks (and especially to java's, like Spring) is what one may call "default behavior". For example, while coding, you can forget to "escape", some html attribute. In a bad framework you'll get errors with corrupt html and security holes. In a good framework you'll have double-escape or an error.
A full list of examples can actually be read in link. What personally I love Lift for is it's statefulness, Scala bindings to HTML like
"#myHtmlNode li div [onclick]" #> ajaxInvoke(...scala code here...)
In the code above, you'll be 100% sure that no one will have access to the contents of ajaxInvoke except for those users you sent the page yourself. And separation of the logic and the view is a relief, of course.
To answer my own question, I have to learn this stuff, no one is going to do it for me. There's OWASP cheatsheets; and also OWASP Enterprise Security API or ESAPI. ESAPI looks promising, though I haven't used it yet.
I have already done all the I18N and GetText things in multiple languages for an existing site.
For selecting one language or another it seems that prefixing urls with path parts like www.domain.com/fr_FR/my_action or www.domain.com/de_DE/my_action is the best way to go, gor Google friendly sites.
I have found this module: Catalyst-Plugin-I18N-PathPrefix And seems to be based on this advent article
Is it the right way (or current best practice) to do this in Catalyst?
It promises that I do not need to change my actions, my required arguments and urls.
Or this plugin/technique makes a overload in the server that I can better avoid rewriting all my urls by hand?
Regards:
Migue
Are www.domain.com/fr_FR/my_action and www.domain.com/de_DE/my_action the same resource, just represented in
different languages? Or would your users see different contents depending on the language they choose (like, I don't know, different news)?
If the answer to the first question is yes I'd rather go for implementing Accept-language header compliance, for example using I18N::AcceptLanguage, which has the additional benefit that it won't interfere in any way with how you designed your URLs.
I take the risks and implemented the Catalyst-Plugin-I18N-PathPrefix plugin. It was easy, and the server load (that was my main concern) seems to be unnoticeable.
Lets say... I should use time to optimize a lot of things of my own code before be concerned about the plugin performance.
Thank you, anyway.
We're reworking some APIs and are considering a REST-style approach, but we're realizing we aren't sure how to deal with certain situations (lists of resources with parameters that influence what is selected, etc.), or even how to effectively structure urls for resources that may be referred to by themselves but are conceptually subordinate to some other entity (think users/posts/comments, but with even more complicated relationships).
We've seen a lot of material on structuring REST APIs for simple cases, but what material is available that talks extensively about making these choices in more real-world scenarios?
First, it's important to note here that REST is an architecture, which means that it simply describes a strategy to follow for addressing and working with resources. It doesn't say how to implement that strategy, or even how to tell if somebody's being RESTful or not.
I also think you're overcomplicating things a bit. Here's a more precise answer for your two specific questions:
how to effectively structure urls for resources that may be referred to by themselves but are conceptually subordinate to some other entity (think users/posts/comments, but with even more complicated relationships)
Even if something is subordinate to something else conceptually, that doesn't necessarily matter for purposes of describing it. For example, let's use your blog example. A Blog may have many Articles, each of which may have one or more Pictures. At first crack, you might expect to be able to reference Pictures with something like:
http://api.example.com/articles/123/pictures/456
But notice that, since Pictures are resources themselves, there's nothing wrong with just doing:
http://api.example.com/pictures/456
(lists of resources with parameters that influence what is selected, etc.)
It's perfectly normal and acceptable to have parameters in a RESTful request. For example, say you want to get the first 500 pictures by date, starting from the twenty-fifth such picture. Your API might support something like this:
http://api.example.com/pictures?limit=500&offset=25&order=desc&by=date
If you can be more precise with you questions, there are plenty of people here who will attempt to help.
Otherwise, here are a few other resources that should be useful.
REST Discuss Mailing List
Rest Wiki
REST Cookbook
The best piece of advice I can give you though, is to stop thinking about how to structure URLs and focus on what links you are going to put in your representations. How to structure your URLs will be easy once you have figured out your media types.
I'll go ahead and assume we're talking about RESTful HTTP :)
This is how you would expose a "list of resources with parameters that influence what is selected":
/list?{search part}
Where the search part is some arbitrary string which you use to target a 'section' of the list resource.
The common way to do this (the way that browsers + html forms work) is to have key/value pairs for each parameter i.e:
/list?name1=fred&name2=dave&name3=matt
This convention for arranging your search part is not mandatory but you will find that following this pattern makes it easier to write HTML for your app. It would be no less valid in terms of HTTP and URI to use the following:
/list?fred,dave,matt
how to effectively structure urls for
resources that may be referred to by
themselves but are conceptually
subordinate to some other entity
In REST there is no such thing as 'structured' URIs. A URI is simply a unique identifier - similarities and patterns in URI structure can make organising server side logic easier and make it 'pretty' for users to look at and figure out - but if you're doing REST there is no relationship between the following:
/foo
/foo/bar
.. unless you create a relationship with a hyperlink from one to the other. This rule of thumb is generally referred to as the 'hypertext constraint' or 'HATEOAS'.
Having said that - there's nothing wrong with 'prettying' up your URIs. Just be aware that (if you want to 'do REST') you should be linking everything together. Most APIs expose 'nested resources' like this:
/countries/england/cities/london
Hope that's helpful :-)
I know that Flickr provides both XML-RPC and REST ways of working with it.
There are standard XML-RPC libraries for every language (For example, Python has a built-in one xmlrpclib).
Standard XML-RPC libraries takes care of the serializing/deserializing as well as sending/receiving the responses.
It seems to me that websites that use the REST style for the same API would end up writing their own libraries in each language. Example: the Yahoo! Search SDK.
To me, it seems that the XML-RPC way is better, but all the evidence is to the contrary. Why?
So:
Why are most web services in REST style, and not in XML-RPC?
Are there downsides to XML-RPC that is not apparent?
Rest is not just easier, its a lot easier.
Xml-Rpc/soap has a lot of moving parts and a hefty amount of overhead, cognitive
and otherwise which (very often) is not needed, its complex and unless you
specifically need some of the features it provides it's just not worth it
Not every service request needs to be packaged up as a formal function call with
parameters
REST is also a formal system that's well defined and a great model for representing
the resources available on the web (hence the term REST)
Having said that, it's easy to make a lot of newbie mistakes using REST so google around for how to use it first, you'll be happy you did.
This is a great question. Unless you are taking advantage of hypermedia for discovery and standard media formats then you are not likely to be getting the benefits of REST. You might as well stick with XML-RPC.
Simple Answer: REST tends to be easier to implement
there are many discussions on that on the web, so I won't go deep on the answer. In short: It's easy. Easy to write, easy to understand, easy to debug. You can write it on your browser and it will probably bring back something useful. Very good.
This easiness come at the price of less "possibilities" but the theory goes that in the long run, easiness might be more worthy.
REST is the native architectural style of the Web. (In fact, it was reverse-engineered from the way the Web already works.) XML-RPC and SOAP attempt to take a very different (procedural, imperative) programming model and adapt it to the web. The result is that REST ends up being cleaner and more flexible.