Ready to build a Rails API, trying to find your way around the Ruby on Rails universe, or just curious about the subject? We’ve put together some basic points that you should know if you’re considering building or working with a Rails API.
And needless to say, Ruby and the Rails environment can seem challenging, if not outright intimidating, when you first approach them; a first-rate Ruby on Rails introductory class can help you find your way through the maze.
What We’re Talking About
First of all, a little background. You may be wondering, “What is Ruby on Rails, and what is an API? I keep hearing these terms, without much good explanation, and I’d like to know what they are, without drowning in a sea of jargon!”
If that’s the case, you’re hardly alone. It’s much easier to toss terms around like you know what they mean than it is to understand them, let alone explain them. So here are a few quick, non-technical, and probably not very precise definitions:
A Little Ruby
Riding the Rails
Ruby on Rails (often known as just Rails) is a web application framework which uses Ruby as its programming language; it is written in Ruby, and when you program for Rails, you will generally write most of your code in Ruby.
“OK,” you say, “what does that mean?”
And That API…
An API is an Application Programming Interface. It’s what one computer program uses to communicate directly with another one. When a program communicates with a user (or vice versa), of course, it does so by means of things that human beings can understand, such as dialog boxes, buttons, and menus. When programs communicate with each other, needless to say, they don’t need to be so human-friendly, so an API generally looks very technical. The communication itself consists of messages, or calls, written in a programming language, and making sue of functions or data provided by the other program. Much of the activity of the software that you encounter every day, on the Internet, on a desktop computer, or on a mobile device, makes heavy use of APIs. You don’t notice it, however, because an API by definition does its work behind the scenes.
Rails and APIs
At this point, you may be saying, “Well, it sounds like Rails is an API!”
That’s basically the case. After all, Rails is pretty much by definition a framework for creating back-end applications that connect to a web browser or to another program of some sort (as opposed, for example, to creating programs that interact directly with the user, and which have minimal contact with other applications). That makes Rails both an API itself (or rather a set of APIs) and a system for developing APIs. Typically, when developers talk about a Rails API, they’re referring to either an API developed using Rails, or a specific set of tools for building APIs in Rails.
What’s In a Rails API?
When you develop a Rails app, what goes into its API? An ultra-simplified version of a Rails API might look something like this:
Get data from an external app Do stuff with the data Send data out to an external app
The API itself would be part of the “get data” and “send data” processes.
Data Transfer and Formats
If you’re transferring data between your Rails app and another application, what format do you use? In a web application environment, the most common languages for data transfer are JSON and XML, so you’ll typically be requesting or sending data in either JSON or XML format. Rails includes a subset of AJAX functionality, making it easy to transfer JSON or XML data; you can request a set of records from an application in JSON format, parse the JSON, then make use of the data — or you can send JSON data to another application at that application’s request.
Control the Output
Rails uses application components called “controllers” to internally handle such things as requests for data; to send JSON data to an app that requests it, you would tell the controller to render the data as JSON (rather than the default XML), using the render method. Render uses the to_json method to do the actual conversion to JSON; the to_json method in turn uses the as_json method as a kind of template for doing the actual rendering, so you can modify as_json to only include specific attributes in the JSON output.
The API’s response to a request should include a response code. You do this by sending the status key to the render method with the appropriate HTTP status code. If there is no content to render (in other words, if you have no JSON to send out, because after all, there’s been an error somewhere), you can render Nothing, like this: render :nothing => true, :status => 404, which returns the infamous “404 Not Found” error.
Security and Authentication
An API can face outward (that is, it can interface with a browser or other external and potentially unknown applications), it can face inward (interfacing strictly with other components of your application or application suite), or both. If your API is going to interface with anything external (and for good security, even if you expect it to only face inward), you need to include authentication so that not just anybody can gain access to your app or your data.
if you’re strictly dealing with a browser interface, you may be able to rely on the browser’s built-in security. But for any other interface, and for full control of security in general, you’ll need to handle authentication directly, by means of custom tokens.
Using the SOA Model
If your application includes several major functions, you can break it up into separate stand-alone components (running as independent programs) which communicate with each other strictly by APIs (rather than, for example, accessing each other’s data or memory space directly). This is typically known as Service Oriented Architecture, or SOA. It gives you not only considerable flexibility (allowing you to swap out entire programs, as long as the APIs remain compatible), but it also allows you to isolate major functions for easier design, and for much easier debugging. A full implementation of the SOA model means in effect that the overall design is centered around the APIs.
Test Your API
It can never be said often enough: no software is ready to ship or deploy until it’s been thoroughly tested. And that goes for APIs just as much as it goes for user-oriented software. You aren’t done developing your API until you’ve fully tested it. API testing is an art in itself, as we’ve discussed in another post, but for now, what you need to keep in mind is that you will need to create code to test every input and output of your API, and to make sure that it behaves properly in the company of any other application with which it will be running.
Much, Much More
There is much more to developing APIs in Rails, of course. The Ruby on Rails universe is large and complex, with its own development philosophy, its own program architecture, and its own terminology. Rails development requires a good understanding of not only what Rails has to offer, but how Rails applications interact with the larger world of web servers and browsers and other web applications, as well as what the Rails development community expects from its members. As with many contemporary development environments, when you enter the world of Rails development, you are also entering into a community of developers, designers, and enthusiasts, a community with its own values and its own way of doing things.
In many ways, the best approach to not only Ruby on Rails, but to the Rails community, is through some of the many online classes in Ruby on Rails, which range from introductory classes to those covering advanced subjects, and on web application development in general.