#BrilliantAPIs

Developing Brilliant and Powerful APIs in Ruby & Python

#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

#BrilliantAPIs

Introductions

Shelby Switzer Notion Queen of API Engineering

Paul Bruce SmartBear API Team Product Manager

#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

#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?

#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

#BrilliantAPIs

Ruby with @switzerly

#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

#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

#BrilliantAPIs

Caching • Key-based caching: cache_key • ETags & conditional GETs:

stale?(last_modified: @book.updated_at.utc, etag: @book.cache_key)

#BrilliantAPIs

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

#BrilliantAPIs

Hypermedia

ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi

See also: gem ‘roar’

#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

#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

#BrilliantAPIs

API in Ruby: Example

#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/

#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

#BrilliantAPIs

Python with @paulsbruce

#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 ...

#BrilliantAPIs

Python: Flask & Django

Fully featured* but a bit more work

Limited, but gets you there fast

* Gypsy jazz legend, Jean Baptiste "Django" Reinhardt

#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

#BrilliantAPIs

API in Flask: Example

#BrilliantAPIs

Python: Django Conventions for common API patterns and scaffolding.

Models Serializers

Permissions

Views

Routing Browsing

#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

#BrilliantAPIs

API in Django: Example

#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

#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

#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

#BrilliantAPIs

API quality across language barriers

#BrilliantAPIs

Ready! API: testing & sandboxing

#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

#BrilliantAPIs

Thank You!

Shelby Switzer @switzerly shelbyswitzer.com

• Paul Bruce • @paulsbruce • paulsbruce.io