This document summarizes a presentation about developing brilliant APIs in Ruby and Python. It discusses choosing between Ruby and Python for APIs and frameworks like Rails, Grape, Flask and Django. It also covers API documentation, testing, and API sandboxing tools. The presentation concludes that Ruby+Rails is best for large projects while Python is great for smaller, as-needed APIs and scripting. It emphasizes the importance of documentation and how Ready! API can help test and sandbox APIs across technologies.

1. #BrilliantAPIs
Developing Brilliant and
Powerful APIs in Ruby & Python

2. #BrilliantAPIs
Housekeeping
• Session is being recorded
• Email once presentation is posted
• Continuous Q&A
–Twitter: #BrilliantAPIs @Ready_API
–Goto Webinar chat panel
–community.smartbear.com

3. #BrilliantAPIs
Introductions
Shelby Switzer
Notion
Queen of API Engineering
Paul Bruce
SmartBear
API Team Product Manager

4. #BrilliantAPIs
What we’ll cover
• API languages, why?
• APIs in Ruby
– Rails 5
– Grape
• APIs in Python
– Django
– Flask
• Docs / M2M / Swagger
• What else is there?
– Testing: function, load,
security
– API virtualization /
sandboxing
– API ecosystem

5. #BrilliantAPIs
APIs in language X?
• Considerations
– What does my team already know?
– How flush is the hiring market?
– What is sustainable long-term?
– What’s easier for *everyone* to deal with?
• Why in Ruby and Python?
• Why not in something else?

6. #BrilliantAPIs
• Java (lots of overhead)
• .NET C# / VB / F# (proprietary stack)
• PHP (wild west)
• Node.js (because javascript)
• C++ (how old are you?)
• GO (fledgling*)
• R (too mathematical) (WTH do I mean by that?)
Why today not other languages?
* https://www.quora.com/What-reasons-are-there-to-not-use-Go-programming-language

7. #BrilliantAPIs
Ruby with
@switzerly

8. #BrilliantAPIs
Ruby terminology
• Gem => an external library
• Bundle => pack up all dependencies
• Rack => HTTP pipeline and req/resp processor
•Rails, Sinatra, Grape
• .rb => code
• Scaffolding => resource MVC generation
• Rake => make-like build utility

9. #BrilliantAPIs
So, Ruby & Rails: a love story
• Ruby: an awesome programming language
• Rails: a web framework for Ruby
• Ruby on Rails
– MVC pattern
– Convention over
configuration
– ActiveRecord

10. #BrilliantAPIs
Caching
• Key-based caching: cache_key
• ETags & conditional GETs:
stale?(last_modified: @book.updated_at.utc, etag: @book.cache_key)

11. #BrilliantAPIs
Testing
• Test::Unit or Rspec
• Unit tests on controllers, models, services
• Request tests for endpoints
• http://matthewlehner.net/rails-api-testing-guidelines/

12. #BrilliantAPIs
Hypermedia
ActiveModel::Serializer.config.adapter =
ActiveModel::Serializer::Adapter::JsonApi
See also: gem ‘roar’

13. #BrilliantAPIs
Documentation
• Swagger gem: https://github.com/richhollis/swagger-docs
• Easy to integrate directly in your code
• Generate docs with a rake task:
rake swagger:docs

14. #BrilliantAPIs
Rails 5 API: Getting Started
1. Install Rails 5:
git clone https://github.com/rails/rails.git
cd rails/
bundle install
2. Generate API:
bundle exec railties/exe/rails new ../books_app --edge --dev --api
3. Create Scaffold:
bundle exec rails generate scaffold books title description:text page_count:integer
4. Migrate the database:
bundle exec rake db:migrate

15. #BrilliantAPIs
API in Ruby: Example

16. #BrilliantAPIs
Ruby+Grape: Sweet, not Sour
• Great for small services
• Can be used with Rails, Sinatra, or alone
• Support for:
– Versioning
– Validation
– (Re)routing
– Error handling / exceptions
• Very code-focused, less data/convention
• Documentation? Boom.
http://www.sitepoint.com/build-great-apis-grape/
http://www.rubydoc.info/gems/grape/

17. #BrilliantAPIs
Grape: Getting Started
1. Install Grape
gem 'grape'
bundle install
2. Create an API file: api.rb
class API < Grape::API
end
3. Create a rackup file (config.ru) to run the API app
require './api'
run API

18. #BrilliantAPIs
Python with
@paulsbruce

19. #BrilliantAPIs
Similarities in Ruby & Python
Lots of “MVC-like” commonalities
models | views | logical control
Templates vs. ViewSets
Routing (routes file vs. urls file)
Database access (ActiveRecord vs. Django data model)
Access control / permissions
Rate limiting
...

20. #BrilliantAPIs
Python: Flask & Django
Fully featured*
but a bit more work
Limited, but
gets you there fast
* Gypsy jazz legend, Jean Baptiste "Django" Reinhardt

21. #BrilliantAPIs
Python: Flask
Install Python.
pip install Flask-API
Create a new directory
Create a .py file
Start typing
Easy to get started, if you know REST
Deployment: WSGI, FastCGI, …
Database access: up to you
from flask.ext.api import FlaskAPI
app = FlaskAPI(__name__)
@app.route("/example/", methods=['GET', 'POST'])
def example():
if request.method == 'GET':
return {'request data': request.data}
elif request.method == 'POST':
return '', status.HTTP_204_NO_CONTENT
raise exceptions.NotFound()
python ./yourfile.py

22. #BrilliantAPIs
API in Flask: Example

23. #BrilliantAPIs
Python: Django
Conventions for common API patterns and scaffolding.
Models Serializers
Permissions
Views
Routing Browsing

24. #BrilliantAPIs
Django: Getting Started
Install Python.
pip install Django
pip install DjangoRESTFramework
Find a Python-savvy editor:
• PyCharm Community
• PyScripter (Windows Only)
• PyDev (Eclipse plugin)
django-admin startproject …
cd …
python manage.py startapp …
INSTALLED_APPS = (
“rest_framework”,
“...”)
python manage.py syncdb
(write some implementation code)
python manage.py runserver

25. #BrilliantAPIs
API in Django: Example

26. #BrilliantAPIs
Django vs. Flask
Django
DjangoCon, increasing interest over time, Books and
online tutorials; great for CRUD, overload for some
Flask
Easy to get started and create, maintenance is hard.
Used by Pinterest & Linkedin

27. #BrilliantAPIs
Django + Swagger:
Why? Because others, that’s why.
django-rest-swagger.readthedocs.org
PyYAML (mileage may vary)
INSTALLED_APPS += ‘rest_framework_swagger’
patterns += url(r'^docs/', include('rest_framework_swagger.urls')),
...and poof!
/docs/ /docs/api-docs

28. #BrilliantAPIs
Lots of APIs: what’s wrong with that?
Microservices
lots of “little” distributed bits
Common problems:
Spaghetti code is imminent.
Unit testing is not enough.
Functional, integration, performance,
and security testing are even more
necessary than ever!
Hypermedia
discrete operations / behaviors

29. #BrilliantAPIs
API quality across language barriers

30. #BrilliantAPIs
Ready! API: testing & sandboxing

31. #BrilliantAPIs
What we’ve learned
Ruby+Rails == Awesome for big projects
Python == Great for as-needed APIs & scripting
Importance of documentation (human &
M2M)
Ready! API bridges gaps across technologies
Links to blogs and examples by email

32. #BrilliantAPIs
Thank You!
Shelby Switzer
@switzerly
shelbyswitzer.com
• Paul Bruce
• @paulsbruce
• paulsbruce.io