Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.

Keith Casey

July 13, 2018
Tweet

More Decks by Keith Casey

Other Decks in Technology

Transcript

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

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

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

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

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

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  6. 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
  7. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  8. 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
  9. WHAT IS BOOTSTRAP? • A clean, simple UI • Standard,

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

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

    they use it for, and how they use it. @CaseySoftware
  12. (Keith, don’t rant here.. take a deep breath.) Forget it.

    I know you’re going to anyway. @CaseySoftware
  13. 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
  14. AGENDA • Assumptions • What is an API? • What

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

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

    create a user account so that I can see my account balance. @CaseySoftware
  17. 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
  18. 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
  19. 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
  20. 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
  21. 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
  22. 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
  23. 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
  24. AGENDA • Assumptions • What is an API? • What

    are we doing now? • What should we do better? • What should we avoid? @CaseySoftware
  25. 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
  26. 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
  27. 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
  28. RECAP • Assumptions • What is an API? • What

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

    goals • Implement APIs according to use cases, not verbs • Move deliberately with intention • Iterate @CaseySoftware
  30. 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