Understandably so, the prevailing theme among developers in the ruby/rails community is against the enterprise. One of the hallmarks of enterprise development is SOAP web services and XML configs. However, I think some of these technologies have a place in the ruby/rails world. One I have discovered recently in working a/ an enterprise team is WSDL/WADL which are documents that describe a web service. To understand, consider some context: Today if I had a job to interface w/ a REST web service I would code up the client in ruby using HTTParty, it’s a lot of boilerplate code and would take most of the day to write and test. Then if the server API changes I need to update my client too – an inconvenience. When we need to interface with a REST API we usually code the client by had, or if we are lucky we can use some type of dynamic tool like ActiveResource if our API is strictly compliant. My points is that our clients are very brittle. This problem has been tackled in a few ways by tools like WSDL/WADL.
When you create your API you attribute you code so that you generate an intermediary description file, usually XML. The description document describes all your endpoints, the parameters they take and the return types. Using this document you can generate the code for your client. SO when the API method parameters change, I don’t have to update my client, I just generate a new one. WADL has many code generators. This notion of API code generation is on absent from the REST world. A fresh approach at it is undertaken by the Swagger project.
Using plugins for your environment, rails, for example, I can annotate my controller with a few basic details and then it can infer the rest of the details about the API. From there it outputs a JSON description document which describes in a structured way HOW to interface my api. The swagger project also comes with a handfull of useful generators too. For example recently I had to make an API for an ios project. I didn’t want to have to type all the code for my IOS API client, so I experimented w/ swagger. I was able to generate the client for all my API in objective C code. Also, it has generators of android and many other platforms. This generated code works perfectly out of the box and allows me to stay up-to-date with the API more easily and focus on the core value of my app, not the network layer.
Here’s an example of my swagger annotated rails controller:
class Api::V1::CardsController < ApiController before_action :set_card, only: [:show, :edit, :update, :destroy] swagger_controller :cards, "Cards" swagger_api :index do summary "Fetches all cards" notes "You may want to use /users/:id/cards to scope by user -- get all user's cards" response :unauthorized response :not_acceptable end swagger_api :show do summary "Fetches a single Card item" notes "This is usually done after the client receives a push request (card broadcast from another user)" param :path, :id, :integer, :optional, "Card Id" response :unauthorized response :not_acceptable response :not_found end swagger_api :create do summary "Creates a new Card" param :body, :user, :user, :required, "A User JSON object" response :unauthorized response :not_acceptable end swagger_api :update do summary "Updates an existing Card" param :path, :id, :integer, :required, "User Id" param :form, :first, :string, :required, "First name" param :form, :last, :string, :required, "Last name " param :form, :status_message, :string, :required, "Status Message" response :unauthorized response :not_found response :not_acceptable end swagger_api :destroy do summary "Deletes an existing Card item" param :path, :id, :integer, :optional, "Card Id" response :unauthorized response :not_found end swagger_api :queue do summary "Queues a card for geo-broadcast" notes "Use this endpoint to broadcast this card to the geo-proximity" param :path, :id, :integer, :optional, "Card Id" response :unauthorized response :not_acceptable end swagger_model :card do description "A Card object." property :id, :integer, :required, "User Id" property :first, :string, :required, "First name" property :last, :string, :required, "Last name" property :status_message, :string, :required, "Status Message" end .... .... ....
Swagger also has a code generator that creates an HTML site that you can use to test your API. The website acts as the client and hits your APIS via AJAX requests.