API Design isn't Just Nouns & Verbs

API Design isn't Just Nouns & Verbs

Say it with me: An API is not CRUD over HTTP. Too often our tools and frameworks encourage us to wrap a thin routing layer around our database and call it an API. While this is quick and easy, it’s also wrong and more wrong. When we consider our API, let’s shift our thinking from nouns and verbs to use cases and goals.

In this session, we’ll step through a straightforward, repeatable process to design interfaces that speed understanding, increase adoption, and make your API the high point of their day.

23365b2ae97212e561fb82442857d8bb?s=128

Keith Casey

July 13, 2018
Tweet

Transcript

  1. API DESIGN IS NOT JUST NOUNS & VERBS D. Keith

    Casey Jr keith@caseysoftware.com / keith.casey@okta.com @CaseySoftware
  2. WHO AM I?

  3. WHO AM I?

  4. WHO AM I? http://TheAPIDesignBook.com

  5. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  6. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  7. ASSUMPTIONS • APIs are an important part of your job

    • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private @CaseySoftware
  8. ASSUMPTIONS • Nothing is perfect • You make mistakes •

    Your providers make mistakes • That other team are knuckleheads @CaseySoftware
  9. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  10. DEFINITION • … is a set of routines, protocols, and

    tools for building software and blah blah • … is a contract between two things describing how they interact blah blah • … is how one piece of software talks to another piece of software blah blah Ref: https://infogalactic.com/info/Application_programming_interface @CaseySoftware
  11. APPLICATION PROGRAMMING INTERFACE @CaseySoftware

  12. APPLICATION PROGRAMMING INTERFACE @CaseySoftware

  13. None
  14. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  15. FRAMEWORKS

  16. GET PUT POST DELETE noun1 /noun /noun1/{id} /noun1/{id} /noun1 /noun1/{id}

    noun2 /noun /noun2/{id} /noun2/{id} /noun2 /noun2/{id} noun3 /noun /noun3/{id} /noun3/{id} /noun1 /noun3/{id} noun4 /noun /noun4/{id} /noun4/{id} /noun1 /noun4/{id} @CaseySoftware
  17. HELLO BOOTSTRAP @CaseySoftware

  18. WHAT IS BOOTSTRAP? • A clean, simple UI • Standard,

    consistent reusable components • The bane of every UI/UX designed out there @CaseySoftware
  19. WAIT… WHY? Bootstrap ignores the application, who uses it, what

    they use it for, and how they use it. @CaseySoftware
  20. WAIT… WHY? Bootstrap ignores the application, who uses it, what

    they use it for, and how they use it. @CaseySoftware
  21. GRAPHQL!!! @CaseySoftware

  22. (Keith, don’t rant here.. take a deep breath.) Forget it.

    I know you’re going to anyway. @CaseySoftware
  23. GRAPHQL IS THE CSV OF API DESIGN (If you tweet

    that, make sure to tag me @CaseySoftware so I get the hate tweets, not just you. ) @CaseySoftware
  24. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  25. As an anonymous visitor to the website, I want to

    create a user account @CaseySoftware
  26. As an anonymous visitor to the website, I want to

    create a user account so that I can see my account balance. @CaseySoftware
  27. THINK ABOUT THE STORY @CaseySoftware

  28. DESIGNING YOUR API @CaseySoftware

  29. STEP 1: IDENTIFY PARTICIPANTS • List consumers of the API

    (directly or indirectly) • e.g. internal developers, external developers, system admins, users of the system • Capture a little about them: location, description @CaseySoftware
  30. STEP 2: IDENTIFY ACTIVITIES • An activity is work that

    produces a desired outcome and is accomplished by one or more participants • An activity might have multiple steps – that’s OK • For each activity, you will capture: the name, the participant(s) involved, and a short description @CaseySoftware
  31. STEP 3: BREAK ACTIVITIES INTO STEPS • Activities are composed

    of steps, with each step being accomplished by a single participant • A step may have stages conducted by multiple participants, but a single step should only be executed by a single participant at a time (aka keep splitting up steps) • For each activity step you identify, you will capture: the activity, the step name, the participant(s) involved, and a short description @CaseySoftware
  32. STEP 4: CREATE API DEFINITIONS • Identify the resources •

    You may start to find dependent/nested resources • Understand which resources are dependent on each other and how @CaseySoftware
  33. RESOURCE RELATIONSHIPS @CaseySoftware

  34. STEP 5: VALIDATE YOUR API • Ensure that your API

    will meet the requirements of everyone using it • Work through each of your use cases @CaseySoftware
  35. VALIDATION OPTIONS Compare API capabilities against UI wireframes Build simple

    mock interfaces in a micro-framework Write example code showing how to use it Write the end user documentation @CaseySoftware
  36. VALIDATION OPTIONS • Compare API capabilities against UI wireframes •

    Build simple mock interfaces in a micro-framework • Write example code showing how to use it • Write the end user documentation @CaseySoftware
  37. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  38. Don’t: Assume you know all use cases @CaseySoftware

  39. Don’t: Collect or Share Extra Data • Cambridge Analytica •

    Why should people to share this information? • How might Keith a bad actor use this information? • You can’t leak what you don’t have @CaseySoftware
  40. Don’t: Leak your own Data • What can I tell

    from using your API? • Do the URLs tell a story? • Does that put customers at risk? • Does it share internal company data? @CaseySoftware
  41. Don’t: Roll your own Encryption • Use an existing library

    that implements an open standard, audit if you prefer • Don’t create your own encryption • No, don’t. You’re not special. • No, not even then. Are you even listening? @CaseySoftware
  42. RECAP • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  43. WHAT SHOULD WE DO? • Understand the user and their

    goals • Implement APIs according to use cases, not verbs • Move deliberately with intention • Iterate @CaseySoftware
  44. WHAT SHOULD WE AVOID? • Don’t try to do the

    whole thing at once • Don’t collect/share data the use case doesn’t need • Don’t leak system/implementation details • Don’t implement your own “encryption” @CaseySoftware
  45. API DESIGN IS NOT JUST NOUNS & VERBS D. Keith

    Casey Jr keith@caseysoftware.com / keith.casey@okta.com @CaseySoftware