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.

Transcript

1. MODELING APIS FOR LEGACY APPS D. KEITH CASEY, JR HTTPS://JOIND.IN/13538 KEITH@CLARIFY.IO @CASEYSOFTWARE
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