Modeling APIs for Legacy Apps - Lone Star PHP

Modeling APIs for Legacy Apps - Lone Star PHP

"API first" is a great strategy for new applications. We can benefit from having a single interface for both our web and mobile presences and free up the developers to use the proper technologies where appropriate. Unfortunately, in the real world, most of us live and breathe legacy applications. The system was conceived long before APIs and we don't have the ability to just restart from the ground up. In this session we'll lay out a strategy on how to successfully model how to build APIs for legacy applications. More importantly, we'll work through the modeling process using a real world production application and index cards to describe each component and how they fit together.

23365b2ae97212e561fb82442857d8bb?s=128

Keith Casey

April 16, 2015
Tweet

Transcript

  1. MODELING APIS FOR LEGACY APPS D. KEITH CASEY, JR HTTPS://JOIND.IN/13538

    KEITH@CLARIFY.IO @CASEYSOFTWARE
  2. None
  3. None
  4. None
  5. http://TheAPIDesignBook.com

  6. How this came about I train a ton of people

    with existing apps that: Are deriving real business value from the app Can’t stop their business for a rewrite But still need an API that implements their business rules, workflows, etc
  7. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  8. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  9. WHAT DO I ASSUME?

  10. Assumptions: You have.. A fully functional application Insight into the

    database/object structures Familiarity with HTTP Verbs & Response Codes A customer asking for API functionality
  11. WHAT ARE OUR GOALS?

  12. Our Goals Maintain a fully functional application Minimize the need

    for rewriting, re-architecting, etc Add a useful API that solves customer problems
  13. WHAT IS OUT OF BOUNDS?

  14. https://leanpub.com/mlaphp

  15. http://TheAPIDesignBook.com

  16. And these sessions Adam Culp’s “Refactoring Legacy Code” Phil Sturgeon’s

    “API Pain Points” Jeremy Lindblom’s “Speak HTTP and Consume APIs with Guzzle”
  17. WHAT ARE WE DOING?

  18. Our Process Assess what we have Model our resources &

    patterns Validate the solution Design the interfaces Build the API
  19. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  20. Where are we starting? What is the existing architecture? Framework?

    ORM? MVC? WTF? Is it stable & secure? Is it maintained or EOL’d? Does it meet the business needs?
  21. Where are we going? What tools (frameworks, etc) can we

    use? Are there mobile apps, partners, customers, etc? Do we have user stories or use cases written?
  22. Web2Project https://github.com/web2project/web2project Forked from dotproject in 2007 MVC-based architecture but

    no framework Strong OO-base with consistent and (relatively) clean interfaces It meets business needs for many (~5k installs)
  23. Some hard numbers

  24. Some more hard numbers

  25. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  26. WHY MODEL MY API?

  27. IF YOU CAN’T MODEL IT, YOU CAN’T BUILD IT

  28. But seriously.. why? We wireframe for great designs, why not

    for APIs? Focus on first on end users, then on developers Better understand & validate the customers’ needs Figure out business processes (beyond CRUD)
  29. The Result Understanding the who will use your API Nouns

    & verbs required High level documentation Validation of the API completeness Drives the next step: API design with REST principles
  30. HOW TO MODEL YOUR API

  31. 5 Steps to API Modeling 1. Identify the participants using

    your API 2. Identify the activities that participants need to achieve 3. Separate the activities into steps 4. Create a list of API resources & methods 5. Validate your API
  32. The Modeling Process

  33. LET’S CONSIDER AMAZON FOXYCART

  34. Step 1: Identify Participants List participants that will consume the

    API directly (or indirectly) e.g. internal developers, external developers, system admins, users of the system Capture a little about them: location, description
  35. Participant Example

  36. Step 2: Identify Activities An activity is work that produces

    a desired outcome & provides business value Most activities will have more than one step Capture information about each: name, participants involved, short description
  37. Activites Example

  38. Step 3: Break into Steps Activities are composed of steps,

    with each step being accomplished by a single participant Activities my be conducted by more than one but a single step should have one participant at a time Sometimes this step requires a SME Capture information about each: parent activity, name, participants, description
  39. Steps Example

  40. Step 4: Collect Resources Start to identify the resources Apply

    your understanding of the resources & their relationships Group the interactions with the resources to make validation easier
  41. Tips for Finding Resources Remember, these are nouns! Resources can

    have properties, like DB tables have columns size, color, quantity, name, ISBN Group like things to more general concepts e.g. coffee, tea, water might be products or drinks, but add muffins and drinks -> products
  42. Resource Definition Example

  43. Step 5: Validate your API Like a good QA team,

    your job is to ensure that your API will meet the requirements of your users Participants are like actors and are the ones using your API Activities are like the use cases or user stories
  44. Methods for API Validation Walk-through UI wireframes for each activity’s

    step validating that the API model supports each one Create test cases (involve QA earlier!) Build workflow or interaction diagrams for typical scenarios The goal: Confidence in what you’re building.
  45. EXERCISE: MODEL AN API

  46. Modeling Exercise Break into groups of 3-5 Get some notecards

    Capture: participants, activities, steps & resources For validation, pair with another group and present your results Don’t worry about verbs, response codes, etc
  47. “Managing a Project” Story 1: As a logged in user,

    I want to create a new project with name, start & end dates Story 2: As a logged in user, I want to add tasks to my existing project with name, start & end dates Story 3: As a logged in user, I want to assign existing tasks to other users Tip: Sometimes workflow diagrams help
  48. Modeling Exercise Story 1: As a logged in user, I

    want to create a new project (name, start & end dates) Story 2: As a logged in user, I want to add tasks to my existing project (name, start & end dates) Story 3: As a logged in users, I want to assign existing tasks to other users 1. Participants 2. Activities 3. Activity Steps 4. Find Resources 5. Validation (present to another team)
  49. Present your API Models

  50. Modeling Review Helps surface all requirements and capabilities Improves understanding

    of the customer’s needs Helps provide a great developer experience Requires iterating over the 5 basic steps
  51. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  52. Impact of Team Design Helps the full team understand the

    API’s purpose the full team understand the scope surface missing APIs earlier in the process encourage feedback from everyone impacted parallelized efforts between teams prioritize sprints
  53. FROM MODELING TO DESIGN

  54. Design Cheatsheet Identify the resources & their relationships (probably already

    defined by your database) Translate your regular verbs to HTTP verbs Identify URI patterns Map HTTP response codes to steps
  55. AND NOW BACK TO AMAZON FOXYCART

  56. URI Patterns

  57. HTTP Response Codes

  58. OVERVIEW ASSESS MODEL DESIGN IMPLEMENT

  59. Our process so far We know where we are We

    know where we need to go We know how we’re going to get there We know the tools we have available ! Now we just need to do it
  60. LET THE FUN BEGIN

  61. Prototyping Techniques Documentation-based Gives you the ability to easily collect

    feedback Puts you ahead when you plan to release Lets you experiment long before there’s code Swagger, RAML, API Blueprint are good options
  62. Prototyping Techniques Simulator-based Gives you the ability to easily collect

    feedback Lets you validate and experiment with calls Gives you a framework to start replacing Slim, Silex, and Lumen*
  63. Clarify’s API Simulator Mon: Model & Design the API Tues:

    Model & Design the JSON payloads Wed & Thurs: Built the Simulator in HAPI & Slim Fri: Had a pint (hey, we have British roots)
  64. TASTES LIKE BURNING

  65. Plan A Add an API “on the side” to act

    as a CRUD layer Gives simple access to the database Can be “well-behaved” without all that old crap Can take advantage of new techniques & tools
  66. Plan A - Broken Add an API “on the side”

    to act as a CRUD layer Gives simple access to the database Our system is more than CRUD! Can be “well-behaved” without all that old crap You mean our business logic? Can take advantage of new techniques & tools
  67. Plan B Build a new system!

  68. Plan B - Broken Build a new system Have you

    been paying attention at all? Besides, what about the business logic? Seriously, are you listening?
  69. A STEP FURTHER

  70. Go back to our system Figure out the reusable pieces

    If there aren’t any, make them Move validation & ACL logic back to the objects Standardize the object interfaces Separate routing logic out of your objects Capture and package workflows into more manipulable entities (dispatchers effectively?)
  71. Wrap those components Now objects just need interfaces Validation and

    ACLs are already included! Business processes become reusable and therefore can be extended/overridden as needed
  72. Mix it all together Combine all the pieces we’ve collected

    Map the resources from the system into our API model & design Implement the base HTTP verbs and map them into the (new?) object methods Now we have a simple API that respects all the business rules & logic we had from before
  73. BUT DOES IT FLY?

  74. Go back to our stories Story 1: As a logged

    in user, I want to create a new project with name, start & end dates Story 2: As a logged in user, I want to add tasks to my existing project with name, start & end dates Story 3: As a logged in user, I want to assign existing tasks to other users Tip: Sometimes workflow diagrams help
  75. Do the pieces still fit? Can we get from the

    beginning of each of our user stories to the end exclusively using the API? Are there still features/functions in the web UI? Are any validations or business flows skipped? And finally..
  76. The Million Dollar Question Can we replace the backend of

    our web UI with our new API without additional components?
  77. RECAP TIME

  78. Our Process Overall Planning & Understanding are KEY Assess -

    We know where we are & the tools we have available Model - We know where we need to go Design - We know how we’re going to get there Implement - And then do it
  79. MODELING APIS FOR LEGACY APPS D. KEITH CASEY, JR HTTPS://JOIND.IN/13538

    KEITH@CLARIFY.IO @CASEYSOFTWARE
  80. http://TheAPIDesignBook.com