Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 104 lines (74 sloc) 4.022 kb
72d06512 »
2012-11-22 introducing rails api
1 ---
2 title: "Introducing the Rails API Project"
3 date: 2012-11-22 09:29
4 ---
5
6 Ruby on Rails is a great tool to build websites incredibly quickly and easily.
7 But what about applications that aren't websites? Rails is still a first-class
8 choice for this use-case, but why settle for good when you could be the best?
9
10 That's why I'm happy to introduce Rails API: a set of tools to build excellent
11 APIs for both heavy Javascript applications as well as non-Web API clients.
12
13 What
14 ----
15
16 Rails' greatest feature is making trivial choices for you. By following
17 conventions, you're able to avoid bikeshedding and only focus on the actual
18 decisions that matter for your application, while automatically building in
19 best-practices. Rails API will do this for the API use-case.
20
21 Here are some initial thoughts on what Rails API will do for you:
22
23 ### A simpler stack
24
25 First, we can remove many parts of Rails that aren't important in an API
26 context: many middleware don't make sense, and all of ActionView can go away.
27
28 To check out exactly what we mean, look at [this
29 part](https://github.com/rails-api/rails-api#choosing-middlewares) of the
30 README, which explains which middlewares we include. The default stack has 22,
31 we have 14.
32
33 Similarly, the structure of ActionController::Base is interesting: it includes
34 a ton of modules that implement various features. This means that we can build
35 an alternate 'controller stack' that doesn't include all of the ones that are
36 in Base. Check out [this
37 portion](https://github.com/rails-api/rails-api#choosing-controller-modules) of
38 the README for a demonstration of the modules we do include. Base includes 29
39 modules, we include 11.
40
41 ### Consistent Javascript output
42
43 One of the biggest issues when building a distributed system is messages that
44 are sent between components. In most Rails-based APIs, this means the JSON that
45 your server side emits, and the JSON that your client consumes. By forming best
46 practices around what JSON is sent around, we can simplify things for
47 server-side and client-side developers.
48
49 The generation of this JSON should be as transparent and simple as possible
85cce05b »
2012-11-22 link to AMS
50 on both sides.
51 [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)
52 is key here. Many new APIs are settling on HAL as a JSON variant that is
53 important to them, and so we'll be considering it heavily.
72d06512 »
2012-11-22 introducing rails api
54
55 ### Authentication
56
57 APIs don't need to handle cookie-based auth, and so a lot of that
58 infrastructure isn't important. Handling other kinds of auth in a simple way is
59 incredibly important.
60
61 ### JavaScript as a first-class citizen
62
63 JavaScript is just as important as Ruby for these kinds of applications, and
64 should be equally as important with respect to tooling, directory layout, and
65 documentation.
66
67 This also means that it should be easy to use the various Javascript frameworks
68 and testing tools. We have representatives from the Ember team on-board, but
69 using other frameworks should be equally fantastic.
70
71 ### Hypermedia
72
73 Many people are interested in building Hypermedia APIs on top of Rails, and
74 so building best-practices around this style should be taken care of, and
75 building them should be easy.
76
77 Where
78 -----
79
aeb9c932 »
2012-11-22 lol copyediting
80 You can find the organization on GitHub at [https://github.com/rails-api](https://github.com/rails-api)
72d06512 »
2012-11-22 introducing rails api
81
b9d3fde0 »
2012-11-23 Fix markdown
82 Originally, these two repositories were located at [https://github.com/spastorino/rails-api](https://github.com/spastorino/rails-api) and [https://github.com/josevalim/active\_model\_serializers](https://github.com/josevalim/active_model_serializers).
72d06512 »
2012-11-22 introducing rails api
83
aeb9c932 »
2012-11-22 lol copyediting
84 We have a Google Group for discussion here: [https://groups.google.com/forum/?fromgroups#!forum/rails-api-core](https://groups.google.com/forum/?fromgroups#!forum/rails-api-core)
72d06512 »
2012-11-22 introducing rails api
85
d2585807 »
2012-11-22 adding link to readme
86 Getting Started
87 ---------------
88
89 To get started, check out the README here: [https://github.com/rails-api/rails-api#railsapi](https://github.com/rails-api/rails-api#railsapi).
90
72d06512 »
2012-11-22 introducing rails api
91 Who
92 ---
93
94 Currently,
95
96 * Carlos Antonio
97 * Rafael França
98 * Santiago Pastorino
99 * Steve Klabnik
100 * Yehuda Katz
101 * Tom Dale
102 * José Valim
103
Something went wrong with that request. Please try again.