Evolving thoughts about building APIs

By: Johnathon Wright on: October 18, 2013

Ever since I saw him speak about the subject at RubyConf 2011, I have been fascinated by Steve Klabnik's ideas about Hypermedia APIs. I have been keeping up with his evolving book on the subject, "Designing Hypermedia APIs":http://www.designinghypermediaapis.com/ and have enjoyed it.

A new client is asking me to design an API. I started with just the basic REST stuff. Having finished 12 resources, I went to work on the "welcome" page. Steve said that an API should be "fully discoverable", and I think this concept is great. Basically, a client should be able to go to a site's index page, look for a certain link (just as a human would with a web browser) and then be taken to the relevant resource. If the URLs change around, that shouldn't matter. The API should facilitate that.

So far, my convention has been to include EITHER links to nested resources or to embed nested resources, and include a 'resource' link... so for a building, it might look like this:

{
  building:
  {
    resource: '/buildings/3241.json',
    tenants:
    [
      { 
        resource: '/tenants/32342.json'
        name: 'Praeses LLC',
        floors: [4, 5, 8],
        reception: 410,
        lease-resource: '/tenants/32342/lease.json'
      },
      {
        resource: '/tenants/32341.json',
        name: 'Dewey, Cheatum & Howe, Attorneys at Law',
        floor: [7, 8],
        reception: '710',
        lease-resource: '/tenants/32341/lease.json'
      }
    ],
    custodians-resource: '/buildings/3241/custodians.json',
    administrativa-resource: '/buildings/3241/administrators.json',
  }
}

so my initial page, the one that has the links to all of the available resources, now looks like this:

{
  buildings-resource: '/buildings.json',
  tenant-profile-resource: /tenants/3234.json',
  building-search-resource: '/buildings/search.json',
  user-session-resource: '/user-session.json'
}

this is fine, I guess. having a search as a resource might phase some people but I have always looked at search as a resource, so I'm cool with it.

I'm now re-visiting Klabnik's book and also a video of him presenting at a conference in LA. He recommends the following mime-type: collection+json, Cj for short.

The same initial page would look like this in Cj:

{
    "collection": {
        "href": "/",
        "items": [
            {
                "href": "/users/21001.json",
                "data": {
                    "email": "your-email@some.test"
                }
            },
        ],
        "links": [
            {
                "name": "tenant",
                "href": "/tenants/3234.json",
                "rel": "profile"
            },
            {
                "name": "tenants",
                "href": "/tenants.json",
                "rel": "resource"
            },
            {
                "name": "buildings",
                "href": "/buildings.json",
                "rel": "resource"
            },
            {
                "name": "user-session",
                "href": "/user_session.json",
                "rel": "resource"
            }
        ],
        "queries": [
        {
            "name": "buildings-search",
            "href": "/buildings/search.json",
            "rel": "search",
            "data": [
                {
                    "name": "q",
                    "value": ""
                },
                {
                    "name": "postal_code",
                    "value": ""
                }
            ]
        }
    ]
}

}

The 'items' element should be the result of the current resource... it isn't clear to me whether the current resource is the user, the tenant profile, or the user session... but obviously that would be much more clear for most of the pages.

h3. Some Confusion

The thing that most confuses me here is the use of 'name' and 'rel' for the links. Should I put {name: 'tenant', rel: 'profile', href: '/tenants/3234.json'} and also {name: 'tenant', rel: 'resource', href: '/tenants.json'} ? or is rel additional data where name can be used to find the needed resource? Or should rel be the primary key for finding specific links?

I have heard that the 'rel' tag should describe how the link relates to the current resource. IIRC, I heard someone else suggest that you have a list of rel tags. Something like:

  • tenants: the tenant collection resource. GET => list, POST => create
  • new-tenant: gives you the fields needed to create a tenant GET => read
  • tenant: a specific tenant's resource. GET => read, POST / PATCH => update, DELETE => destroy
  • tenant-profile: if the current user is associated with a specific tenant, this is a link to that tenant's profile
  • user-profile: resource for the current user
  • users: user collection resource
  • user
  • building-search: allows you to create searches and view results. GET/POST => search. Having search be its own resource allows you to do interesting things like caching search results, and having a page that will return the input fields
  • new-building-search: the page that would return the search fields. For instance, q and zipcode.

h3. Decision Time

So this seems like a lot more fun. I'm about to deploy this app and presumably someone will start building the front-end, so this is the decision point-of-no-return... should I stick with what I have, or start using something like collection+json?

My big question at this point is whether it solves a problem I anticipate having with my current process.

|Cj feature|can I do it now?| |list the current resource|yes| |links to related resources|yes| |links to parent or unrelated resources|unknown| |form parameters|yes| |form options a-la a drop down|no|update: now that I think about it, I can sorta do it. Not as neatly, though.| |rel tags|no| |errors|yes|

Although this is a well-thought-out hypermedia mime type, my impression is that it might add some complexity for the client. Complexity is fine, as long as there is a benefit. SOAP, for instance, adds complexity but, in my experience, doesn't provide any benefit over REST in exchange for the complexity.

Looking at this, the only thing that worries me is not having rel tags... though I can't think of an example where that would be a problem. Conclusion: stick with what I have.

References

Designing Hypermedia APIs Collection+JSON Primer (and comments) Collection+JSON support in Roar!





Comments:

air max said: Thank you a lot for providing individuals with an exceptionally wonderful chance to discover important secrets from this website. It is often so fantastic and jam-packed with fun for me and my office colleagues to visit your blog a minimum of 3 times per week to study the new things you have. And definitely, I'm certainly fascinated with the tremendous tips and hints you give. Selected 1 tips in this posting are undeniably the simplest I've had. air max [url=http://www.airmax270.us.com]air max[/url]

nike react said: My wife and i were so joyous Jordan could conclude his homework via the precious recommendations he came across out of the web site. It's not at all simplistic just to continually be giving for free solutions which often most people could have been selling. We really understand we have the writer to appreciate for that. Those explanations you have made, the straightforward website navigation, the relationships you will assist to foster - it is mostly spectacular, and it is facilitating our son in addition to us believe that the subject matter is pleasurable, which is certainly particularly important. Thanks for all! nike react

jordan retro said: I wish to show my passion for your generosity for individuals who require help with this one study. Your personal dedication to passing the solution throughout ended up being quite significant and have surely enabled professionals like me to attain their targets. Your own interesting advice denotes so much a person like me and much more to my mates. Thank you; from everyone of us. jordan retro

supreme said: I precisely wished to say thanks once again. I'm not certain the things that I would have undertaken in the absence of the suggestions revealed by you concerning such field. It had been a real troublesome scenario in my circumstances, but understanding your well-written manner you resolved that made me to leap for contentment. I'm happier for this service as well as sincerely hope you really know what a powerful job that you are doing instructing people using a blog. Probably you've never encountered all of us. supreme

supreme new york said: I wish to show some thanks to this writer for bailing me out of such a challenge. Because of scouting throughout the the web and seeing things which are not productive, I was thinking my entire life was well over. Living devoid of the answers to the difficulties you've resolved by way of your entire guideline is a serious case, and ones which might have in a wrong way affected my entire career if I hadn't encountered the website. Your good natural talent and kindness in maneuvering all the stuff was very helpful. I am not sure what I would've done if I had not encountered such a solution like this. It's possible to at this point look ahead to my future. Thanks for your time very much for your expert and results-oriented help. I won't hesitate to recommend your blog post to any individual who desires guide on this issue. supreme new york

curry 7 sour patch said: I have to show my affection for your generosity for men who need help on this situation. Your very own dedication to passing the message all-around turned out to be astonishingly useful and have consistently enabled most people just like me to reach their endeavors. Your amazing warm and helpful help can mean so much a person like me and far more to my office colleagues. Thanks a lot; from all of us. curry 7 sour patch

moncler said: Youre so cool! I dont suppose Ive read something like this before. So good to search out anyone with some unique ideas on this subject. realy thank you for beginning this up. this web site is something that's needed on the web, someone with just a little originality. useful job for bringing something new to the web! moncler

kd 10 said: Good day! I simply would like to give a huge thumbs up for the good info you've gotten here on this post. I might be coming back to your blog for more soon. kd 10

off white jordan 1 said: After research a couple of of the blog posts on your web site now, and I truly like your approach of blogging. I bookmarked it to my bookmark website listing and will likely be checking again soon. Pls take a look at my web site as well and let me know what you think. off white jordan 1

supreme clothing said: Youre so cool! I dont suppose Ive read something like this before. So nice to search out any individual with some unique ideas on this subject. realy thanks for beginning this up. this website is one thing that is wanted on the internet, somebody with a bit originality. useful job for bringing one thing new to the web! supreme clothing

kd 13 said: Would you be desirous about exchanging hyperlinks? kd 13

jordan shoes said: After examine a few of the blog posts on your web site now, and I actually like your approach of blogging. I bookmarked it to my bookmark website list and might be checking back soon. Pls check out my web site as effectively and let me know what you think. jordan shoes

jordan 1 off white said: I was very pleased to seek out this net-site.I wished to thanks in your time for this wonderful read!! I positively having fun with every little bit of it and I've you bookmarked to check out new stuff you blog post. jordan 1 off white

kd13 said: I'm often to blogging and i really respect your content. The article has actually peaks my interest. I'm going to bookmark your web site and maintain checking for brand spanking new information. kd13

a bathing ape said: I'm typically to running a blog and i really appreciate your content. The article has actually peaks my interest. I am going to bookmark your web site and keep checking for new information. a bathing ape

chrome hearts said: very nice put up, i actually love this website, keep on it chrome hearts

golden goose outlet said: This actually answered my problem, thanks! golden goose outlet

balenciaga sneakers said: The following time I read a blog, I hope that it doesnt disappoint me as a lot as this one. I imply, I know it was my choice to read, however I actually thought youd have one thing fascinating to say. All I hear is a bunch of whining about something that you would fix in the event you werent too busy in search of attention. balenciaga sneakers

jordan shoes said: Thanks so much for providing individuals with such a spectacular possiblity to read from this website. It can be so pleasurable and also stuffed with a great time for me and my office acquaintances to search your web site really 3 times a week to study the latest things you have. And lastly, we are certainly satisfied with all the fantastic tactics served by you. Certain 1 areas in this article are really the most efficient we have all had. jordan shoes

michael jordan shoes said: Thanks for every one of your efforts on this site. My mom take interest in carrying out investigation and it is easy to see why. A number of us notice all concerning the compelling manner you provide effective techniques through this web blog and therefore attract contribution from some other people about this concept plus our own child is without question becoming educated a whole lot. Have fun with the remaining portion of the new year. You are always carrying out a first class job. michael jordan shoes

yeezy boost 350 v2 said: A lot of thanks for all your efforts on this web site. Kate really loves carrying out investigations and it's simple to grasp why. Most people learn all concerning the lively medium you give functional techniques on your web site and as well cause contribution from other ones on the topic plus our favorite simple princess is undoubtedly discovering a whole lot. Enjoy the rest of the new year. You're conducting a great job. yeezy boost 350 v2

off white jordan 1 said: I definitely wanted to make a brief remark so as to express gratitude to you for all of the stunning facts you are giving at this site. My rather long internet research has at the end of the day been compensated with awesome points to write about with my visitors. I would say that many of us website visitors are unequivocally fortunate to dwell in a perfect site with very many awesome people with beneficial strategies. I feel very lucky to have seen the web pages and look forward to really more pleasurable moments reading here. Thank you once more for a lot of things. off white jordan 1

birkin bag said: My spouse and i ended up being now joyful that John managed to finish up his basic research because of the ideas he had out of the web pages. It's not at all simplistic to simply choose to be giving for free tactics that people might have been trying to sell. And we fully grasp we've got the website owner to be grateful to for this. The entire illustrations you've made, the easy blog menu, the relationships you will aid to promote - it's got most astounding, and it's facilitating our son in addition to the family recognize that this theme is thrilling, and that is rather mandatory. Thanks for everything! birkin bag

kd shoes said: I want to express my gratitude for your kindness giving support to women who absolutely need help with this particular area of interest. Your real dedication to getting the solution up and down appeared to be pretty practical and has specifically enabled individuals just like me to reach their dreams. The insightful useful information indicates a whole lot a person like me and still more to my office workers. Regards; from all of us. kd shoes

supreme hoodie said: I must express my appreciation to the writer for rescuing me from such a problem. After researching through the internet and getting solutions that were not pleasant, I believed my entire life was over. Living minus the answers to the difficulties you have fixed by way of this article is a serious case, as well as those which could have in a negative way affected my career if I had not discovered your web blog. Your good competence and kindness in handling almost everything was invaluable. I'm not sure what I would have done if I hadn't come upon such a thing like this. I am able to at this moment look forward to my future. Thanks so much for the expert and result oriented help. I won't hesitate to endorse your web sites to any individual who ought to have direction on this matter. supreme hoodie

yeezy boost 350 v2 said: I simply wanted to make a brief comment to be able to appreciate you for these amazing instructions you are posting on this website. My rather long internet look up has now been honored with awesome ideas to share with my guests. I would state that that we website visitors are very lucky to exist in a wonderful site with so many marvellous people with valuable things. I feel rather blessed to have used the web page and look forward to some more exciting moments reading here. Thanks once again for everything. yeezy boost 350 v2

yeezy 700 said: My wife and i were quite relieved when Ervin managed to carry out his basic research with the ideas he discovered in your web page. It is now and again perplexing just to choose to be giving out techniques which often other people could have been trying to sell. And now we do understand we now have the website owner to give thanks to for that. The main explanations you've made, the straightforward website navigation, the relationships your site help to create - it's most awesome, and it's really letting our son in addition to us reckon that this situation is fun, and that's seriously fundamental. Thank you for all the pieces! yeezy 700

moncler said: My husband and i were absolutely fulfilled when Louis could finish off his preliminary research using the precious recommendations he got from your blog. It's not at all simplistic to simply be giving away facts which usually the others may have been making money from. And we do understand we need the writer to appreciate for that. The specific illustrations you made, the simple website menu, the relationships you can make it easier to foster - it is mostly unbelievable, and it's aiding our son and us recognize that this article is excellent, which is exceedingly important. Thank you for the whole lot! moncler

longchamp outlet said: Thank you for each of your efforts on this web page. My niece takes pleasure in carrying out research and it's easy to see why. Many of us learn all relating to the dynamic medium you deliver reliable guidelines on this blog and improve participation from people on the point then our favorite princess is undoubtedly starting to learn a lot. Enjoy the rest of the year. You're carrying out a powerful job. longchamp outlet

stone island sale said: I must show some appreciation to you just for bailing me out of such a setting. As a result of scouting through the world wide web and finding things which are not helpful, I thought my life was gone. Living devoid of the answers to the problems you've resolved as a result of your good article content is a crucial case, as well as those which could have in a negative way damaged my entire career if I hadn't noticed the blog. Your main know-how and kindness in playing with every aspect was useful. I don't know what I would have done if I hadn't encountered such a point like this. It's possible to at this time look forward to my future. Thank you very much for this expert and result oriented guide. I will not hesitate to endorse your web blog to any person who ought to have guidelines on this problem. stone island sale

adidas yeezy said: I not to mention my buddies have already been following the great pointers located on your website and then all of a sudden developed a terrible suspicion I had not thanked the site owner for those secrets. Most of the men are actually as a result joyful to learn all of them and have in actuality been making the most of them. I appreciate you for being indeed thoughtful and for pick out varieties of awesome subject matter millions of individuals are really wanting to discover. My very own sincere apologies for not expressing gratitude to earlier. adidas yeezy

yeezy boost 350 v2 said: I must voice my respect for your generosity supporting persons who really want help with this important concern. Your special dedication to getting the message throughout appeared to be really practical and has constantly allowed guys and women like me to realize their targets. This warm and friendly tips and hints entails so much to me and especially to my colleagues. Many thanks; from each one of us. yeezy boost 350 v2

adidas yeezy said: I truly wanted to type a word to be able to say thanks to you for these pleasant information you are showing here. My rather long internet look up has at the end been honored with good quality facts and techniques to talk about with my best friends. I 'd state that that many of us visitors are unquestionably lucky to dwell in a fantastic site with very many lovely professionals with useful suggestions. I feel very grateful to have encountered your website page and look forward to many more pleasurable times reading here. Thanks once more for a lot of things. adidas yeezy

adidas yeezy said: I am glad for writing to make you understand what a perfect discovery my princess encountered studying your blog. She came to find too many details, with the inclusion of what it is like to have a wonderful giving character to have other individuals completely gain knowledge of specific impossible subject areas. You actually exceeded visitors' expected results. Many thanks for showing such interesting, trustworthy, revealing not to mention cool guidance on the topic to Gloria. adidas yeezy

curry 6 said: I just wanted to type a brief note in order to appreciate you for all of the unique strategies you are sharing at this website. My extensive internet search has now been compensated with professional details to go over with my friends. I 'd state that that many of us site visitors are quite fortunate to dwell in a really good website with very many brilliant professionals with useful strategies. I feel rather grateful to have discovered the web page and look forward to so many more awesome minutes reading here. Thanks a lot once more for a lot of things. curry 6

yeezy shoes said: I needed to write you this very little remark in order to thank you so much once again regarding the fantastic methods you've featured above. It's simply remarkably generous of people like you to convey openly what exactly a number of us could have offered for sale for an ebook to end up making some dough for themselves, most notably seeing that you might have done it if you ever decided. The tricks also worked to provide a good way to fully grasp that many people have similar keenness similar to mine to understand lots more on the topic of this issue. I'm certain there are several more pleasurable instances in the future for folks who take a look at your blog. yeezy shoes

kyrie irving shoes said: I precisely desired to thank you very much all over again. I do not know the things that I could possibly have taken care of without the techniques shown by you relating to such a concern. It previously was an absolute daunting circumstance for me, however , taking note of the well-written way you managed that took me to weep for contentment. I'm just thankful for your guidance and even have high hopes you are aware of an amazing job you're carrying out teaching some other people via your blog. I am certain you've never met all of us. kyrie irving shoes

off white hoodie said: I wanted to put you the tiny observation to finally say thanks a lot the moment again considering the lovely views you've featured on this site. It was so remarkably generous of you to convey extensively what most of us could have offered as an electronic book to get some dough for themselves, precisely given that you might well have done it in case you considered necessary. These inspiring ideas as well worked to become good way to be sure that some people have similar eagerness like my own to know the truth a lot more with reference to this problem. I am sure there are thousands of more pleasant opportunities in the future for folks who take a look at your blog. off white hoodie

jordan shoes said: My wife and i were glad Louis managed to carry out his research through the entire precious recommendations he gained out of your web page. It's not at all simplistic just to happen to be freely giving methods people today might have been selling. We do know we now have the writer to thank for this. The most important illustrations you've made, the simple website menu, the relationships you can help to promote - it's got many impressive, and it's really leading our son in addition to our family reckon that this content is enjoyable, which is extremely important. Many thanks for all the pieces! jordan shoes

moncler outlet said: My husband and i felt really delighted Edward managed to round up his web research using the precious recommendations he was given using your web page. It is now and again perplexing to just find yourself freely giving helpful tips that many many others may have been trying to sell. So we consider we need the blog owner to thank because of that. The main explanations you have made, the straightforward website menu, the relationships you can help to instill - it's got most amazing, and it is helping our son in addition to the family believe that that theme is pleasurable, which is certainly particularly essential. Thank you for the whole thing! moncler outlet

supreme clothing said: I have to express appreciation to you for bailing me out of this type of crisis. As a result of exploring through the world-wide-web and coming across solutions that were not productive, I was thinking my life was done. Existing without the strategies to the issues you've solved by way of the posting is a crucial case, and those that might have adversely damaged my entire career if I hadn't noticed your web page. That skills and kindness in dealing with all areas was crucial. I'm not sure what I would've done if I had not discovered such a subject like this. I can now look forward to my future. Thank you very much for this expert and sensible guide. I won't hesitate to suggest your blog to anyone who wants and needs tips on this area. supreme clothing

hermes online said: My spouse and i got very satisfied Edward managed to finish off his basic research using the ideas he acquired out of the web page. It's not at all simplistic to simply find yourself handing out strategies which often some other people might have been selling. So we do understand we have got the blog owner to appreciate for that. The entire illustrations you have made, the straightforward web site navigation, the relationships you will assist to create - it's all fantastic, and it's letting our son in addition to us believe that that matter is awesome, which is certainly seriously serious. Thank you for the whole thing! hermes online

hermes belts said: I wish to show some appreciation to this writer for bailing me out of this particular crisis. After checking throughout the search engines and obtaining things that were not productive, I believed my entire life was gone. Existing devoid of the solutions to the problems you have solved through your good article content is a serious case, as well as the ones which could have badly damaged my entire career if I hadn't discovered your web blog. The competence and kindness in controlling everything was vital. I am not sure what I would have done if I hadn't come across such a thing like this. I am able to at this moment look ahead to my future. Thank you so much for the specialized and effective help. I will not be reluctant to suggest your web sites to any individual who would like guidelines on this area. hermes belts

yeezy 380 said: I would like to express my appreciation to you for rescuing me from this particular predicament. Just after looking through the online world and obtaining things which were not beneficial, I was thinking my entire life was over. Being alive without the presence of strategies to the difficulties you have resolved through the posting is a crucial case, and the kind which could have negatively affected my entire career if I had not come across your web page. Your primary capability and kindness in playing with every aspect was vital. I am not sure what I would have done if I hadn't encountered such a step like this. It's possible to now look ahead to my future. Thanks for your time so much for your expert and sensible help. I won't hesitate to refer your blog to any individual who will need tips on this matter. yeezy 380

hermes birkin bag said: I wish to express my appreciation to you just for rescuing me from such a challenge. After researching through the search engines and meeting notions which were not pleasant, I figured my entire life was gone. Living devoid of the answers to the issues you've sorted out through your good site is a serious case, and those which may have badly affected my entire career if I hadn't encountered the blog. That understanding and kindness in maneuvering the whole thing was very useful. I don't know what I would have done if I hadn't come upon such a stuff like this. I am able to at this moment look forward to my future. Thanks so much for the reliable and effective guide. I will not be reluctant to endorse your web sites to anybody who requires guidelines about this subject matter. hermes birkin bag

kd 12 said: I am just commenting to let you be aware of of the great experience my friend's princess experienced browsing the blog. She came to understand a lot of details, with the inclusion of how it is like to possess an ideal helping character to get the rest quite simply fully understand selected extremely tough things. You actually surpassed our own expected results. I appreciate you for imparting the precious, dependable, educational and also unique thoughts on this topic to Evelyn. kd 12

off white outlet said: Thanks for your own work on this site. My mum really likes making time for investigations and it's simple to grasp why. My partner and i notice all regarding the compelling medium you render both interesting and useful things through the blog and in addition encourage response from visitors on that article then our daughter is actually starting to learn a whole lot. Take pleasure in the remaining portion of the year. You're conducting a pretty cool job. off white outlet
Back