Question

So I’m building an application in Rails 3 using Devise as my authentication mechanism. I have all my controllers and views working. Our web site is humming along. Now we’d like to export our routes to 3rd party developers. The problem is how.

Here’s the list of things I think I need to figure out.

1. Third party authentication. I am trying to get it straight in my head what I need to do. We have an existing user base and tokens have been generated for all of them with the Devise authentication model. Now I need to provide some kind of security. My current line of thinking is to set up an OAuth Provider to manage private keys and then somehow set up our web app as one of the applications the 3rd party developer can gain access to. Is that the correct line of thinking or am I over-engineering it?

2. Generate public facing documentation for our REST endpoints. While the rake routes is nice for internal developers, I really think we need something more along the lines of swagger-ui. the problem is rails doesn’t generate the appropriate json/xml calls for swagger-ui. Which as I understand it are required in a true REST service. Such as resource listing, and operations listing on a resource.

Thanks in advance for any direction you can give me in these arena’s!

Answer 1

I would definitely recommend OAuth if there is a security element for your users. That is, you want someone to be able to edit multiple users details via their service then used 3-legged OAuth (Provider, User, Client). Otherwise go for the 2-legged OAuth (Provider, Client.)

If you want to implement a 3-legged OAuth API then I wrote a tutorial which is available here. It uses Devise and Oauth2.

As for the documentation, I would go as far as to write custom documentation instead of relying on tools. Twitter have a very well documented API, I use that as a basis for the RESTful APIs I write.