Welcome to the Workshop: Getting setup instructions

Connect to the wireless network IllinoisNet_Start

Install the chrome extension ‘Postman’ https://www.getpostman.com/

$ git clone https://github.com/cucode/practical_web_api_design_UoI_WebCon_2016.git

$ cd practical_web_api_design_UoI_WebCon_2016.git

$ npm start

That should launch a browser tab with a link to the Swagger Editor

If that works you’re all set. Raise your hand to let us know if you have any problems.

Gitter: http://bit.ly/1SAH0Rt

Practical Web API

Design

UoI WebCon Apr 27 2016

Your Presenters

Wes Cravens - Director of Technology, Pixo, Urbana

Marty Kane - Senior Lead Developer, Pixo, Urbana

Aaron Lee - Plant Labs, San Francisco (Remote from Urbana)

John McCaffrey - Equifax & Thinkful (Remote from Champaign)

​

Introduction

Overview of the Topics

It’s a big topic to fit into 3 hours

We encourage working in pairs

Welcome to the team

Getting Started - Is everyone set up?

https://gitter.im/cucode/practical_web_api_design_UoI_WebCon_2016

​

Why APIs are valuable

API Economy

Expose your business information and application engine to other consumers/applications

Common interface methodology to facilitate future interoperability with other systems

The more ‘standard’ you are the less you must rely on ‘semantics’

Standardized clients for you API (Browsers are pretty cool) API should be consumable with just a browser

Sharing Information to other departments

Maybe the API is your business

Balancing the Costs of Building and Designing an API based on business needs

Business advantages - Spreadsheet and ‘mashing up’ information.

​

The Core Components of an API

Authentication

Registration

Versioning

Exercise 1

Explore Aspects of a Few Popular APIs

The anatomy of an API Call

​

Postman for Developers

Postman for Non-Developers

HTTP Request

HTTP Verbs

Response Codes

Response Body

Exercise 2

Test and Explore APIs with Postman

Designing an API

Means designing the endpoints and their responses

Start with the logical domain

What are the nouns? What are the verbs?

Much of what you know about OO design applies here

• Single Responsibility

You are providing the terminology your clients will use to think about the API

Designing an API

DON’T get caught up in the implementation

DON’T worry about formats, JSON vs. XML

DO Be willing to make big changes as you realize what’s part of the domain

DO Think about the calls as well as the response

DO Think about how you navigate the API

Designing an API - Nouns

Items you can represent in a data structure

• They can be real items like a book
• Or abstract concepts like a permission

They have some representation in the system

​

Designing an API - Nouns

Can be singular

Or collections of Nouns

• These are collections of singles
• Should be the plural of your Noun

Or even nested!

• /post/{id}/comments/{id}
• /book/{title}/chapters/{number}

Designing an API - Actions

• Actions on a Noun or collection
• (note: In english these would be “verbs”, but that term is already used)
• (Which brings up a good point, don’t overload terms in your API)
• Actions can happen to the whole, to a singular, or to a subset
• LIST : `GET /noun`
• Singular : `GET /noun/:id`
• Subset : `GET /noun?filter=condition`

​

Designing an API - Actions

• May require extra information
• Especially true for creating a new singular
• `POST /noun` key: value
• Don't get caught up on format of POST data
• JSON, XML, POST data is an implementation detail
• Can succeed or fail
• What gets returned with a success?
• What gets returned with a failure?

Designing an API - Example

S3 Bucket Manager

• Allows someone to create a bucket, specifying the name
• Gives them credentials to the bucket
• Lets them manage permissions
• List all buckets owned by a user

Designing an API - Example

Nouns:

Verbs:

Designing an API - Example

Nouns:

Bucket

Key

Permission

Owner

Verbs:

Designing an API - Example

Nouns:

Bucket

Key

Permission

Owner

Verbs:

Create

Destroy

Grant

Designing an API - Example

S3 Bucket Manager

Allows someone to create a bucket

Call: PUT /buckets/{name}

Returns: 201 and a url for the bucket

​

Designing an API - Example

S3 Bucket Manager

Gives credentials to the bucket

Call: PUT /buckets/:name:

Return: 201 and a representation of the bucket including keys

​

Designing an API - Example

S3 Bucket Manager

Lets them manage permissions

Call: PUT /buckets/:name: the body includes permissions

Return: 200 and a url for the bucket

​

Designing an API - Example

S3 Bucket Manager

List the buckets owned by a user

Call: GET /buckets?user={username}

Return: 200 Listing of all buckets owned by {username}

​

Exercise 3 - Group Work

Convert the Resources of your Domain into an API

​

1 - Pizzas

2 - Tacos

3 - Ice Cream

4 - Omelets

5 - Hot Dogs

6 - Potatoes

7 - Froyo

8 - Waffles

9 - Pancakes

10- Crepes

​

Break

Exercise 4 - Group Work

Swap APIs with another group for them to review

Exercise 4 - Group Work

​

Join up with the group that has your API. Discuss

Documentation

• Goals for documenting our API
• Bridge the semantic gap
• Easy to maintain and explore
• Computer-readable
• The Open API Spec
• Swagger / tools

​

Some extra topics and reading list

Roy Fielding’s Dissertation; Fielding Constraints & REST

Richardson Maturity Model

Hypermedia / Media-Types

Further Reading

Some Highlights: Heroku API Design Guidelines, API Developer Weekly, Design-first APIs in Practice, The API Evangelist

​

Avoid Perfection Paralysis and Malcontent

Q&A

Lunch discussion?

Birds of a feather session?

Thank You

Enjoy the rest of conference! Maybe see you at lunch.

Wes Cravens - Director of Technology, Pixo, Urbana

Marty Kane - Senior Lead Developer, Pixo, Urbana

Aaron Lee - Plant Labs, San Francisco (Remote from Urbana)

John McCaffrey - Equifax & Thinkful (Remote from Champaign)

https://github.com/cucode/practical_web_api_design_UoI_WebCon_2016