2020-02-sacon-nyc

Shared content repository for 2020-02 SaCon NYC edition of "Design and Build Great Web APIs"

SACon NYC

Here's the landing page for this workshop at the O'Reilly SACon web site: https://conferences.oreilly.com/software-architecture/sa-ny/public/schedule/detail/79966

The Book

This workshop is based on the upcoming eponymous book from Pragmatic Publishing. You can download excerpts and sign up for the early release project at the book's home page here: https://pragprog.com/book/maapis/design-and-build-great-web-apis

Starter Project

All the code projects in this workshop are creawted from a "base" starter project. You can FORK that project for your own use here: https://github.com/mamund/api-starter

General Topic Outline

Below is the big-picture outline of the morning workshop. We'll see working examples of each step in the process along with exerecises for select parts of the outline.

Principles

• API-First
• HTTP-Web-REST
• Modeling Interactions

Designing

• Document the Story (see https://github.com/api-tool-kit/company/blob/master/assets/company-story.md)
• Diagram the Flow - https://WebSequenceDiagrams.com
• Describe the API w/ ALPS - http://alps.io/spec/drafts/draft-01.html

Building

• Sketch - https://app.apiary.io
• Prototype - https://app.swaggerhub.com/home
• Build (NodeJS & DARRT) - https://github.com/mamund/api-starter

Releasing

• Test - https://www.postman.com/
• Secure - https://manage.auth0.com/dashboard
• Deploy - https://dashboard.heroku.com/apps

Related Github Projects

All the working examples will be derived from the following projects. NOTE: The COMPANY and CREDIT-CHECK examples will get the most attention in this workshop.

• https://github.com/api-tool-kit/activity
• https://github.com/api-tool-kit/account
• https://github.com/api-tool-kit/company
• https://github.com/api-tool-kit/onboarding
• https://github.com/api-tool-kit/credit-check

Tools

While, you can enjoy the workshop without having to do hands-on coding/design work, haveg a few tools on hand can enhance the experience. Below are the tools used to put together the workshop. The items w/ an asterisk (*) indicate online tools that offer free online accounts

• Your Favorite code editor
• Git & Github (*)
  • install local git tooling
  • https://git-scm.com/
  • set up git push/pull for Github
  • https://github.com/
• WebSequenceDiagrams.com (*)
  • online-only tool
  • https://WebSequenceDiagrams.com
• Apiary API Markdown (*)
  • online-only tool
  • https://app.apiary.io
• SwaggerHub OpenAPI Editor (*)
  • online-only tool
  • https://app.swaggerhub.com/home
• NodeJS & npm
  • install NodeJS & npm
  • https://nodejs.org/en/
• Postman.com for testing (*)
  • install Postman client
  • https://www.postman.com/
  • install newman CLI for Postman
  • https://www.npmjs.com/package/newman
• Auth0 for security (*)
  • online-only tool
  • https://manage.auth0.com/dashboard
• Heroku for deployment (*)
  • register at Heroku for deployment
  • https://dashboard.heroku.com/apps
  • install Heroku CLI
  • https://devcenter.heroku.com/articles/heroku-cli

Slides

You'll find the slides from the day's workshop here: https://github.com/mamund/2020-02-sacon-nyc/tree/master/slides