I am planning the rest architecture of my current project and I want to know which architecture is better. My data consists of users, topics and posts.
So if my usecase requires to get all posts for a specific topic, how should I design it?
I know two approaches:
http://restip/api/topics/:id/posts
http://restip/api/posts/?topicId
So which one is recommended and are there better solutions?
The better way is the first, this link explain all the conventions (Base on ruby on rails conventions).
http://microformats.org/wiki/rest/urls
Is more easy to read a topic with the id have posts.
That's really just a matter of taste. Just be consistant everywhere in your API.
In my opinion though, your second approach is good. It is better to keep it simple by preferring "shallow" URLs (with fewer levels) when possible :
/topics/:topicId
/posts/:postId
/posts/?topic=:topicId
You can add fancy URL rewrite rules later, if needed, so that for example:
/topic/:topicId/posts maps to /posts/?topic=:topicId
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 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.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
How to version REST URIs
I'm new to REST-ful API design, and I can't seem to find a consensus for how to implement API versioning in the REST-ful style. The possibilities I've come across include:
URL-based (eg. /myApi/version5/someCall)
This approach works great for both servers and clients ... but it doesn't seem very REST-ful (urls are supposed to correspond to resources, and the API version really isn't a part of the resource)
Payload-based (eg. $.ajax({data:{version:5, ...)
This approach works great compatability-wise, but:
A) The server needs to actually parse the payload to determine the version (which tends to put the version-checking logic "deeper" in than it should be)
B) Again, from what I can tell of the philosophy, this isn't very REST-ful (as I understand it, the data I POST should only be the data for the resource I want to create)
Header-based (eg. Accept application/json;version=5)
This approach was suggested here, which I've found to be an excellent resource on how to make a REST-ful API. In this particular case however I keep running in to problems, as no matter what I do I can't seem to get jQuery to send the version in the header.
Now, I'm sure I can eventually solve the jQuery issue in approach #3 if I try, but it made me think that I might be going down the wrong road with header-based versioning; if I'm having trouble, it seems likely the consumers of our API would also.
So, when creating a REST-ful API, can anyone please explain which versioning approach:
A) will work with the best with other bits of technology (browsers, frameworks, etc.)
B) implement the "REST-ful" philosophy most faithfully
C) is most common (this one's not important on its own, but it does tend to be an indicator of the first two)
In other words, what's the best way to handle versioning in REST-ful APIs?
Solution 1 seems practical and simple. For your reference twitter(api.twitter.com/2) and linkedin(api.linkedin.com/v1) uses URL Based Versioning, Google Data(&v=1.0) uses Payload Based. My hands-on experience is in URL Based versioning.
If you want to do an analysis, check this api directory
I would strongly suggest solution 1, it's clear and easy - not only that even StackOverFlow uses it: https://api.stackexchange.com/2.1/questions?order=desc&sort=activity&site=stackoverflow :)
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 need to create a internal website and can't figure out if we should be writing our own, or using an existing framework.
Most of the website will essentially be a front end to a database. We need to have a number of people enter data into forms. We then want to be able to show different views of all this data -- including running small queries (e.g. how many resources do we have with attribute 'X'). As is usually the case with this, we will want to tweak the UI on a regular basis.
There actual data design is not a simple 1:1 mapping of resource to entry. For example, we might track several attributes for one item as the "base set of data" for that item. Then we could have several additional sets of data.
Imagine a recipe application. You might have a recipse for a starter. This could then be referenced by several other recipes that need that same information.
I feel like this is best suited for a general framework (Ruby on Rails, Django, etc), but I wonder if it might not be good for a "traditional" CMS platform like Drupal? I specifically mention Drupal since the people that would develop this have the most knowledge using php and MySql.
I usually lean towards wanting to use an existing platform, but am interested in other people's thoughts. To give you an idea of scope, I would imagine if we wrote this from scratch we are probably talking about 3-5 weeks of development.
Would you recommend writing our own, or using an existing framework? If you would suggest using something that exists what would you recommend?
Would you consider this to be best suited for a straight framework or a straight CMS?
Thanks!
It's possible that Drupal will be a good solution for you, though you'll probably need a few key additional modules like the "Content Creation Kit" (CCK) and "Views".
Unlike other web CMS systems (WordPress, Exponent, phpNuke), Drupal treats your entries as a "pool" of content, from which you pull various subsets for different areas of your site.
There is a lot of documentation for Drupal (almost too much), the biggest problem is finding the piece that's relevant to what you're trying to achieve. Diving on to one of the interactive IRC channels can be a good idea, as the community is quite helpful and is almost always willing to give you a pointer in the right direction.
The power, flexiblity and capability of Drupal is both its biggest strength and weakness - I know it took me a bit of effort to get my head around key concepts, and I'm far from being a Drupal Expert.
One last comment: Having written my own CMS from scratch, which I abandoned in favour of Drupal, I'd suggest your 3-5 week estimate is likely on the light side.
Stay away from Drupal for any site that requires customized functionality. I recently used Drupal for a website at work, and it was VERY difficult to figure out how to get it to do what I wanted it to do. There is a lot of documentation out there, but all of it is unhelpful -- it answers very specific questions about specific issues but does not provide any context as to how you would approach building the site as a whole. If you're a programmer, using a more general framework will probably work better, as CMS's are designed for a specific kind of site, and if you want your site to have non-standard functionality you are going to be fighting the system instead of working with it. If your developers are most experienced in PHP, try one of the PHP frameworks that mimics the architecture of Rails -- e.g. cakePHP or CodeIgniter.
CMSes usually make sense when you have a broad and potentially expanding array of different content types and modes you need to handle. Drupal has literally dozens. Given than you mentioned RoR, it sounds like what you need is more of a MVC style framework. Maybe similar to the sort of thing stackoverflow was built with. .NET an issue for you?
If you are really limited to 3-5 weeks, however, I think a Rails-based strategy makes sense so go with RoR or CodeIgniter
If Drupal can do what you need easily I would say go with Drupal. I don't know much about Drupal though.
Otherwise, what you describe sounds like a data driven web app or more like a reporting app. It sounds like you might have some very specific needs or that users might want very specific needs in the future. That is something hard to get from premade software since you have no idea what users are going to request. Since I'm a programmer I would probably want to build it myself.
Funny you should ask... I just came across this in SD Time's Linkpalooza this afternoon:
Ten free powerful content management systems…
There are at least 4 more mentioned in the comments to this post.
It seems to make little sense to develop a new one with so many from which to choose!
BTW, this is neither a recommendation nor endorsement of any particular CMS.
Treat Drupal as a framework. Core modules + CCK + Views is a good start to build on.
If you're doing something that you might want to expose to other applications, consider the Services module. A lot of interesting things have been done with flex frontends connected to drupal running services with amfphp.