This document discusses building and testing a JSON API with Rails and RSpec. It covers the development workflow, API design including RESTful principles and versioning, and using Rails and RSpec with testing gems like FactoryGirl and rspec_api_documentation. Finally, it outlines a mini-hackathon project to build a crowd funding API with basic functionality like user authentication, project creation and pledging.

1. Building and Testing Rails
JSON API with RSpec
Eddie Lau (3dd13@42la.bs)
23 Oct 2014

2. Agenda
• 1. Development Process
• 2. API Design
• 3. Rails, RSpec and Gems
• 4. Mini-hackathon

3. Mini-hackthon
build your own API

4. Setup (Mac)
Ruby
curl -sSL https://get.rvm.io | bash
rvm install 2.1.3
Gems needed
gem install bundler
gem install rails
Sample project code
git clone http://github.com/3dd13/api_rspec_workshop
cd api_rspec_workshop
bundle install

5. 1. Development Process

6. Workflow
Initial
• UX / UI / Wireframe
• Communication / Endpoint needed
• API Design
• Test cases
• GREEN
Add feature
• UX / UI / Wireframe
• Communication / Endpoint needed
• API Design
• Upgrade version (if needed)
• Add / Update test cases
• GREEN

7. 2. API Design

8. Architecture
Frontend Js Client
HTTP API
Backend Server

9. 42 Labs Stack
AngularJS (Browser or Mobile)
RESTful API - JSON
Ruby on Rails / Node.js

10. 42 Labs Stack
Admin Web
Customer Web
(AngularJS)
Customer Mobile
(AngularJS)
Ruby on Rails
HTML
JSON API
JSON API

11. RESTful
• GET http://example.com/projects.json
• GET http://example.com/projects/:id.json
• PATCH http://example.com/projects/:id.json
body: {project: {name: “”, …}}
• POST http://example.com/projects.json
body: {project: {name: “”, …}}
• DELETE http://example.com/projects/:id.json

12. Standard / Convention
Always
GET, CREATE, UPDATE, DELETE resource

13. RESTful ?
1. Search projects by date range
GET http://example.com/projects/search.json
2. Create multiple projects
POST http://example.com/projects.json
body: [{project: {name: “”, …}, {project: {name: “”,…}} ]
3. Update multiple projects (e.g. mark as archived)
PATCH http://example.com/projects/archive.json
body: { project_ids: [1, 3, 5]}

14. Suggestion
not always true !
1. Search projects by date range
GET http://example.com/projects.json?date_range_filter=last_week
2. Create multiple projects
POST http://example.com/project_batches.json
body: {project_batch: [{ project: {name: “”} }, …]}
3. Update multiple projects (e.g. mark as archived)
PATCH http://example.com/projects/1,3,5.json

15. RESTful Authentication
• Step 1: User Sign In
POST http://example.com/users/sessions
body: {email: “user@example.com”, password: “password”}
Response:
{session: {auth_token: “123abc456defxxxxx”}}
• Step 2: Access Protected Action
GET http://example.com/users/projects/1.json
Header: X-AUTH-TOKEN 123abc456defxxxxx

16. Versioning
• GET http://example.com/api/v1/projects.json
• GET http://example.com/api/projects.json
Accept: application/vnd.charityspring.v1

17. 3. Rails & RSpec
and other gems

18. Testing

19. rspec
expect(status).to eq 201
expect(response_body).to be_json_eql(expected_json)
expect{ do_request }.to change{ Project.count }.from(0).to(1)

20. factory_girl
FactoryGirl.define do
factory :user do
sequence(:email) { |n| "user#{n}@example.com"}
password "password"
end
end
user = FactoryGirl.create(:user)

21. rspec_api_documentation
rake docs:generate

22. 4. Mini-hackthon
build your own API

23. Setup (Mac)
Ruby
curl -sSL https://get.rvm.io | bash
rvm install 2.1.3
Gems needed
gem install bundler
gem install rails
Sample project code
git clone http://github.com/3dd13/api_rspec_workshop
cd api_rspec_workshop
bundle install

24. Run test cases
rake db:migrate
rake
rake docs:generate

25. Create seed data
rake db:seed

26. Code walk through

27. Note:
1. password is plain text
2. no database index was created
don’t use it in production, feel free to change the code

28. Start coding ~
1. Visitor wants to see a list of crowd funding projects
2. Visitor wants to search crowd funding projects by name
3. Visitor wants to sign up using email and password
4. Visitor wants to sign in using email and password
5. Member wants to create a crowd funding project
6. Member wants to see a list of crowd funding project she created
7. Member wants to pledge a crowd funding project
8. Member wants to see a list of crowd funding project she pledged

29. Advanced
1. Member wants to pledge and pay via Paypal / Stripe
2. Add a new API endpoint to v2