University of Illinois WebCon April 27th 2016
Wes Cravens (@WesCravens), Marty Kane (@martinekane), Aaron Lee(@wwkeyboard) & John McCaffrey(@j_mccaffrey)
Web based APIs have emerged as the defacto standard for powering our applications across several clients. We use our Web APIs to power our mobile platform applications, our browser client applications, automation systems, b2b exchanges and much more. There is a surge of business logic moving from behind closed curtains out into the World Wide Web where it can be leveraged and consumed in unimaginable ways. Some go as far as to suggest that the 'API Economy' is the new frontier in the Information Age.
This workshop will outline the most practical strategies and technologies that we should consider while designing and building our APIs. Know to what extent you should consider the original Fielding constraints (RESTful design) and know when to make trade-offs. You're main goal should be to build a successful and consumer friendly API that is still flexible and change tolerant. We'll explore practical answers to these difficult decisions.
- Overview of the Fielding Constraints
- Modeling your problem domain
- Hypermedia as the Expression of Application State (HATEOS)
- What is a resource? Good endpoint design
- HTTP Verbs - The reality
- Value flexibility and consumption over perfection. Why 'perfection' is unrealistic?
Table of Contents generated with DocToc
- Required Tooling
- Workshop agenda and timetable
- Seating and assistance with Tool installation
- Greetings and Introduction to the Workshop (WC)
- Why HTTP APIs are Valuable & The Core Components of an API (JM)
- The anatomy of an API Call and Demo of Postman (JM)
- The Components of an HTTP API Domain (JM)
- Documentation and the Open API Specification (MK)
- Good Design: Avoild Perfection Paralysis and Malcontents (WC)
- Wrap up, Q&A
- References
Our workshop is designed to leverage tools that you can use online with a browser any time. However we've all been to conferences before, so we know that it's wise to not be 100% reliant on a functional internet connection espectially if you're asking 60 people to download and install tooling before hand. So with that in mind we've also chosen tools that can be used offline using simple local webservers that can run on our laptops.
Installing these items before the workshop will help us all support each other in the event that there are any network connection discrepancies during our workshop.
- Chrome Google's Browser
- Git Very popular version control system
- Node.js A javascript runtime environment for your computer.
- This repository
- Postman We'll be using the Chrome plugin version.
- Gitter We'll use this for real time chat.
- [Getting Started Guide]
-
8:45 - 9:00 Seating and assistance with Tool installation
-
9:00 - 9:05 Greetings and Introduction to the Workshop
-
9:05 - 9:20 Why HTTP APIs are Valuable & The Core Components of an API
-
9:20 - 9:30 Exercise 1 - Explore Aspects of a Few Popular APIs
-
9:30 - 9:40 The anatomy of an API Call and Demo of Postman
-
9:40 - 10:00 Exercise 2 - Test and Explore APIs with Postman
-
10:00 - 10:15 The Components of an HTTP API Domain
-
10:15 - 10:35 Exercise 3 - Convert the Resources of your Domain into an API
-
10:35 - 10:45 Break
-
10:45 - 11:00 Exercise 4 - Swap APIs with an other Group for them to Review
-
11:00 - 11:10 Exercise 5 - Bring Groups Together to Discuss the APIs
-
11:10 - 11:15 Documentation and the Open API Specification
-
11:15 - 11:35 Exercise 6 - Specify, Serve and Explore your API
-
11:35 - 11:45 Good Design: Avoild Perfection Paralysis and Malcontents
-
11:45 - 12:00 Wrap up, Q&A
- Setup instructions
- Ensure that cohorts have the installed technologies (At least half)
- Raise hand if there are any problems, we'll come around
- Introduction of Workshop Speakers
- Overview of the topics
- It's a big topic to get into 3 hours
- Encourage Paired programming and group exploration
- Getting started
- 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.
- Authentication
- Registration
- Versioning
- Postman for Developers
- Postman for Non-Developers
- HTTP Request
- HTTP Verbs
- Response Codes
- Response Body
- Nouns vs Verbs (Comment vs Search; Shopping Cart vs Purchase)
- Hierarchy / Relationships (toppings vs. pizza vs. purchases)
- How to “psudocode” an API
- GET /thing/subthing?query=thing
- Response code, { name : thing, name : think }
- Errors
- Quick example of fake domain
- Goals for good API documentation
- Required to bridge the Semantic Gap
- Should be easy to consume/explore
- Should be easy to maintain
- Should be a computer-readable contract and support code generation
- API Specification via the Open API Specification (swagger)
- Swagger tools to create and explore documentation
- Fielding Constraints ???
- Richardson Maturity Model
- Hypermedia / Media-Types
- Be patient, Dealing with malcontent, Don't be dogmatic
- Further Reading
- Is there interest in a birds of a feather lunch or evening discussion group?
-
API Developer Weekly A digest and review of recent publications in the API development space.
-
The Map of A Tweet A colorized visualization of the JSON representation of a tweet
-
REST: I don't Think it Means What You Think it Does • Stefan Tilkov Common misconceptions on what REST means
-
Design-first APIs in Practice A pretty good overview of leading the design of your API from a consumer point of view with a particular emphasis on the Design-Thinking approach.
-
Do you really know why you prefer REST over RPC? A good post on RPC vs REST, especially the follow-up comments
-
DigitalOcean API documentation Not that the API is the best, but I really like the structure of the documentation. It includes examples for multiple languages.
-
GitHub API The GitHub API is known for its good design and usability.
-
Stripe API The Stripe online payment processing API. Introduced a new level of developer friendliness with the disruptive introduction of its API.
Practical Web API Design by Wes Cravens, Marty Kane, Aaron Lee & John McCaffrey is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at https://github.com/cucode/practical_web_api_design_UoI_WebCon_2016.
