List of Figures

Chapter 1. What makes an API irresistible?

Figure 1.1. A blog incorporating a Twitter feed as well as API functionality for sharing to multiple social networks. A widget provides buttons for each of the social networks—Google+, Twitter, LinkedIn, and Facebook—and this widget incorporates that network’s API into the site in a manner that’s easy to implement.

Figure 1.2. Example API interactions with a monitoring application. When the monitoring application detects a change, it can propagate it to a website, mobile application, SMS notification, or email.

Figure 1.3. This chart describes an adaptations mashup using Freebase, Amazon, and Netflix. The user is presented with a grid of book-based movies matching a specific genre, and for each of the movies, the user is given the opportunity to watch the movie on Netflix or purchase the book on Amazon. This is an example of a mashup combining multiple APIs to create an integrated experience for the user.

Figure 1.4. The basic interactions with an API are direct connections with the back-end server or servers, and a well-defined interaction with clients on the front end. This allows for countless frontend applications, whether mobile, website desktop, or system integrations, without changes to the back-end servers.

Figure 1.5. This example shows how common terms map to API concepts. Resources are unique names, the methods are easy to understand, and options and context allow the client to express specific concepts via the API transaction.

Figure 1.6. A customer interaction at a coffee shop. Though this diagram seems complicated, realize that the interaction represents exchanges you’ve had multiple times with service providers. An acknowledgment can be as simple as a nod from the cashier, and each of the requests made by the customer is a simple request.

Figure 1.7. This diagram shows multiple systems integrated together. On the left, you can see Fitbit, MyFitnessPal, and Withings feeding into the Runkeeper system, which can aggregate all of your fitness data in one place. The picture on the right shows Netflix and all of the various types of devices it has integrated with, cementing its leadership in the video industry.

Figure 1.8. The process must contain all of these factors in order to be successful. Treat your platform like a first-class product and watch it thrive.

Figure 1.9. These are examples of different business values with the associated metrics. The most important concept to understand is that you want to have a business value that’s meaningful to people outside of the API team, and metrics should support that value in a way that’s meaningful to your overall organization or company.

Figure 1.10. Organically grown APIs are unrelated to each other. This results in duplicate (and sometimes inconsistent) code, different interfaces to the same information, and extra work for the consumers of the various APIs to implement integrations with applications.

Figure 1.11. Blueprint definition for a simple “notes” API. Blueprint uses Markdown for the formatting, and as you can see this is a human-readable document. As long as someone understands the basics of HTTP interactions, they’ll be able to parse this document—which means that your product manager, customers, and the other development teams you interact with will be able to understand your API long before you even start coding.

Figure 1.12. OpenAPI sample markup. Unlike Blueprint, OpenAPI (previously Swagger) supports JSON and YAML as its markup languages and features the ability to include abstractions for objects in the system (such as a “user” or a “contact”), which encourages readers to consider the resources of the API in an object-oriented way.

Figure 1.13. RAML from MuleSoft. RAML supports Markdown, as Blueprint does, but the schema that’s created is more expressive than Blueprint. Additionally, like the OpenAPI framework, they support abstract objects more natively than Blueprint, making it easier to implement and maintain consistent APIs across a complex system.

Figure 1.14. API Commons was designed for companies to define and store their schema models so that other companies with similar APIs can leverage these existing schemas when building their own APIs. This allows the developers consuming these APIs to interact with similar systems, rather than needing to translate between numerous different representations of the same object.

Figure 1.15. Building an API from other companies’ schemas can allow you to use the schemas generated by different API providers when designing your own API, while still making it easy for developers who have already implemented these other APIs to integrate with your platform.

Chapter 2. Working with web APIs

Figure 2.1. An HTTP request will always have a method and will be sent to a specific URL, or resource. Depending on the specific call, headers may be sent to specify information about the request. If the call is designed to write new information to the system, a body will be sent to convey that information.

Figure 2.2. A response will always have a status code, and a well-designed platform will send headers to provide information about the response (such as size or the content type). For most requests, a body will be sent back from the server to provide information about the current status of the resource.

Figure 2.3. Example result of a web call in a browser. The response is JSON, a common markup language for web APIs. As you can see, the formatting makes it easy to understand the content of the response.

Figure 2.4. This diagram represents the complete set of interactions with the API system. The GET request reads the current value of the resource, whether it’s a list or an individual item. POST is only allowed at the list level, and creates a new resource in the system. PUT updates and DELETE deletes an existing resource. All four of the needed methods, Create, Read, Update, and Delete, are represented in this diagram.

Figure 2.5. The Chrome browser makes it possible to see information about the request and response headers, the body of the request or response, and other useful information about the transaction. Although browsers aren’t designed to send PUT or DELETE responses, the information provided here can go a long way in helping you to understand the interactions with the platform.

Figure 2.6. This is an example of a call being inspected by HTTPScoop. On this basic landing page, you can see the Request URL, representing the resource. The content type of the response, status code, and response size are also provided.

Figure 2.7. Here you see a representation of the API toppings list in JSON, the markup language used by the platform. As described, the curly braces indicate an object, or dictionary, and the square brackets represent an array, or list of objects.

Figure 2.8. The application view for the toppings list shows the same information, as shown in figure 2.4. This screen is created by calling the toppings list and creating the HTML based on the returned information. If the list changes on the server, both figure 2.4 and figure 2.5 would change, with both showing the same information in different ways.

Figure 2.9. This HTTPScoop screen shows a list of all the calls made by the system. In this case, you can see the DELETE method is called to remove the /toppings/2 resource from the system, and it was successful, as indicated by the 2XX response in the code column.

Figure 2.10. Once the topping has been deleted from the system, the HTML representation of the toppings list no longer shows the deleted topping. If the platform call is made (to /toppings) you’ll see that the change is reflected in the JSON representation as well.

Figure 2.11. The Edit a Topping screen allows you to change the title of an existing resource.

Figure 2.12. When you change the title of an existing resource, the information is sent to the server, and it sends back the new representation of that item. In this case, the object is quite simple; the title is the only field that can be changed. This is a simple demonstration of how an update works on an API platform.

Figure 2.13. The list of toppings now includes Ham and Pineapple; the Pickles have been deleted (thank heavens), and the Pepperoni has been changed to Ham using an update. Again, if you made a call to the /toppings resource you’d see the changes shown in the JSON representation as well.

Figure 2.14. The Add a Topping screen is designed to add new toppings to the system. As mentioned earlier, a create action is generally represented by a POST operation, and that’s what the system will do in this case.

Figure 2.15. HTTPScoop POST request/response. The only field needed to create a new topping is the title, and it’s set to Extra extra cheese (yum!). The response shows the ID and title—the entire representation—of the newly added item.

Chapter 3. API First

Figure 3.1. This is an API that was set up as many of the first platforms were created: the main product interacts directly with the back-end system, leaving the APIs as second-class citizens in the product hierarchy. Any new changes or features in the main product have to be duplicated in the API, resulting in feature inconsistency and incompatible resource representation.

Figure 3.2. When an API is one of many different interfaces into the back end, the representation of a simple item (such as a user) can be different in many ways. Additionally, if the back end (in this case, the database) is changed to add more information, the interactions with each of the client systems will need to be changed, as will the clients of the API itself. This creates a large amount of technical debt because any change to the system has to be duplicated in several different places.

Figure 3.3. In an API First model, the back end only interacts with the API, which in turn drives the main product and all other implementations—the main product, mobile device, and other integrations. This reduces the need for duplicate code and allows each client to focus on exactly the pieces it needs.

Figure 3.4. When different implementations are maintained for different clients, the user experience is different—and if, for instance, the reporting system adds new functionality to include the company for a specific user, the API would need to add it. In this system, the mobile and integration clients would need to add it as well.

Figure 3.5. In an OAuth request, the client and server both know the application and user keys, but they also have “shared secrets” at the application and user levels. The request is built using the nonsecret data, and the encryption is done using the shared secrets. The client creates the request and signs it with the shared secret, sending it to the server. The server takes the request and also signs the request, and then compares the signature it created with the one sent by the client. If they match, then the client passes the authentication check and the request is allowed to proceed.

Figure 3.6. Twilio’s system, with APIs for both internal and external functionality. Although Twilio uses its billing and configuration APIs only internally, the discipline it exercises in making sure that everything it does uses the same API system helps to ensure that the system is consistent and robust.

Figure 3.7. 3scale’s evolution from standard implementation to API First moved it from a system where most of the customer visible functions were available via the platform to a system where each function within their system worked via the same API platform. Again, this made 3scale’s system more robust and made it easier to expose new functionality to users as requirements dictated.

Chapter 4. Web services explained

Figure 4.1. HTTP transaction between a client (application) and server (platform). The HTTP request will always be sent to a specific URL defining the resource; most requests will also have headers to add context to the request, along with parameters to refine the item itself. If the request is an update or create action, a body will be sent as well. The HTTP response always has a status code indicating the success or failure of the exchange, as well as headers describing the type and size of the content.

Figure 4.2. 418 status code exchange demonstrating a somewhat silly interaction with the coffeepot protocol as defined by the W3C. Note, though, that it’s similar to the other transactions we’ve seen; the client sends a request for a particular resource, and the platform responds with a status code indicating the answer—in this example, a response that the object isn’t the expected coffeepot, but rather a teapot.

Figure 4.3. Actions and their associated HTTP methods. To perform all the needed actions for a complete platform, CRUD must be supported. HTTP contains methods for each of these actions, making it a great framework on which to build an API.

Figure 4.4. This is a human version of the programmatic transaction that follows. The interaction between the people demonstrates exactly how transactions work. As you can see, all the requests and responses between the client and the server map directly to an easy-to-understand interaction between people.

Figure 4.5. HTTP verbs and their components. Each HTTP request must always have a method along with the resource: the address for the specific item as well as an action to be taken for that item. Note that the Success status code listed for each of the methods is slightly different but still follows the pattern of 2XX, indicating success.

Figure 4.6. Go to irresistibleapis.com/demo to see the main HTML page. Remember that on the back end, this page is calling the /toppings endpoint in the API.

Figure 4.7. Once you’ve started the website in Chrome, you can activate the C Developer Tools using the path View > Developer > Developer Tools.

Figure 4.8. Now that you’ve opened the Developer Tools, switch to the Network tab to get to the information you want to see.

Figure 4.9. Change the settings to activate Preserve Log so that the HTTP traffic will stay in the queue for inspection.

Figure 4.10. As calls are made through the browser, they each show up in a separate line in the Network Log section of the Chrome Developer Tools. To get to where you can understand the interactions, select the toppings resource in the network log.

Figure 4.11. Once the toppings resource is selected, you’ll be able to see information about the call in the right-hand column, including the response body, request, and response headers. Explore the various tabs on the right side to learn more about how the pieces work together.

Chapter 5. Guiding principles for API design

Figure 5.1. As with the resources and methods described in this figure, using inconsistent error codes means developers have to hunt through documentation to learn what the errors mean. Using the standard HTTP status codes helps alleviate this problem and saves times for your client developers.

Figure 5.2. Even using the API Explorer for Flickr, you can see that there’s no standard HTTP status code (although this API is using HTTP) and that the message format doesn’t follow any standard industry pattern.

Figure 5.3. In a mobile interface, the main goals include logging in and user authentication, a performant and efficient platform, and an exact and complete response. The illustration on the right demonstrates what an ideal mobile/platform interaction looks like.

Figure 5.4. The interaction between a client and Twitter can include multiple types of interactions. The initial request and response is usually logging in, or client authentication. From that point, a client can either add new updates to the system or read the current feed of updates in the system. Each of these transactions works the same way: a request is sent from the client, and the server processes the request and sends a response back to the client.

Figure 5.5. When waiting for changes from a platform, a client can continue asking the server whether there’s been any change, but this is expensive in terms of time and resources on the client and server side both. A subscription model, where the client “subscribes” to receive updates from the system, is much more efficient.

Figure 5.6. Common API interaction between Netflix and a client device or application

Figure 5.7. Manifest format for API Commons

Figure 5.8. API Commons top-level definitions

Figure 5.9. Strict REST versus API with expansion

Figure 5.10. Complex LinkedIn request: specific attributes for particular fields

Figure 5.11. Etsy reworked its platform to be API First and strongly RESTful and decided to address the issue of mobile integration using the BeSpoke system, which batches calls together on the server end and sends back the aggregated information to the caller.

Figure 5.12. This diagram shows what reference documentation can look like in a system that has been designed by modeling a schema. The documentation you see here, which is dynamic and allows for exploration, is created entirely from an OpenAPI specification.

Chapter 6. Defining the value for your API

Figure 6.1. Twilio has a strong developer portal. All portals should have API documentation as a quick link, but many other items are required to make a great portal. Articles about the system can help developers understand the underlying technology, such as the Security section here. Most important, the Getting Started section includes guides and libraries to help developers get going quickly, keeping the Twilio five-minutes-to-first-call goal in mind.

Figure 6.2. Twilio’s API interacts with services in the messaging, voice, and video space. Each of these functions works directly with the same API, making it easy for developers to integrate multiple segments into applications. The API is like a central routing station, moving requests from the client developer’s application into the correct part of the Twilio API portal.

Figure 6.3. Blog using a widget that creates and drives sharing icons for the main social platforms. Because each platform has a well-understood, well-described, and consistent API, developers can easily create integrations into these social platforms, and blog owners can plug in widgets with this functionality in a few minutes.

Figure 6.4. Facebook’s multitude of API offerings show the vast number of integration points it has created into its system. The most basic social platform integration—sharing widgets—is quite easy to use, but the Facebook platform includes complex integrations into the social graph (how people are related), monetization for games, and a game platform that provides much of the needed functionality for creating Facebook games.

Figure 6.5. Before the FedEx platform became readily available, FTD enjoyed a virtual monopoly in the flower-sending industry for nonlocal deliveries. It worked with local florists (and was able to impose strict guidelines and pricing) and made it easy for consumers to send flowers anywhere in the country. But the system wasn’t set up so that the best florists were successful; FTD made it so that partnering with FTD was an important business decision for florists.

Figure 6.6. Once FedEx provided a platform for local florists to use, it was no longer necessary to partner with a large company such as FTD in order to receive and process floral deliveries remotely. Now that there are ways for local companies to deliver their specific products with a minimum of effort, the competition is focused around the value of the products and not partnerships with specific companies.

Figure 6.7. Netflix is an excellent example of how an API can streamline a user’s experience. The API itself provides basic search and information about movies, including people and genres associated with them. The company additionally provides a movie player on most major platforms, which is integrated with the Netflix platform via the API, so a user can always find and learn about movies before watching them. The API makes it possible for other devices and applications to do the same thing so that users’ experience is consistent across all the applications they use.

Figure 6.8. When determining the success of your API, the simplest things to measure are the number of developer keys and/or number of calls. Without measuring the types of calls or number of end users, these pieces of data aren’t at all indicative that the API is creating value for your company.

Figure 6.9. As a system with an API as its main product, Twilio can easily measure things that demonstrate API success. It can measure standard company metrics like revenue per employee, because all of its revenue comes through the API. Additionally, it can measure things about the accounts such as the number of conversions to paying accounts and the number of accounts with a high and consistent volume of calls.

Figure 6.10. Social platforms have a specific set of goals; increasing the amount of activity in the system and the frequency of interactions by users both indicate a healthy ecosystem. When determining strong metrics for your social application, think carefully about what kind of metrics will indicate that users are more closely tied to your system (frequency of interaction) or providing new interesting content (frequency of writes).

Figure 6.11. Basic mobile interaction. Without focusing on the specific information in the call, an initial call from the client to the platform will include authentication information and specifics about the resource being requested. On the platform side, the authentication data will be processed by the auth segment of the platform, and if the credentials are authenticated (who is it?) and authorized (can they do the action?), the request is passed through to the platform, and a response is sent back to the client.

Figure 6.12. The SendGrid platform is like a central routing station for email interaction. It can schedule and structure outgoing emails to provide for tracking clicks, bounces, and spam filtering. The user interaction with the system is simple and straightforward.

Figure 6.13. Context.io creates a database out of an email box. The contents of the email box are read, and functions are exposed for searching, filtering, sorting, and formatting that data. Additionally, when changes are made in the data by Context.io to add tagging or other additional information, Context.io writes these changes back to the originating email box.

Figure 6.14. Twitter has examples to help understand how use cases are mapped to API functions. For each of the examples listed here, the interaction point provides benefits for both Twitter and the end user. Great APIs will always create this kind of mapping—if an API improves the end-user experience as well as improving the system itself, it’s most likely to become successful and well used.

Chapter 7. Creating your schema model

Figure 7.1. The actions for the PizzaToppings API need to support CRUD—create, read, update, and delete. At the list level, the only two actions are to create a new item and read the list. For an individual topping, you can read the item information, update the item, or delete a specific item.

Figure 7.2. When you want to add a new API into Anypoint, the only required fields are the API name and Version name. The API endpoint is handy to have in your schema, and I suggest you make the description reasonably clear.

Figure 7.3. The information you put into the Add API form turns up at the top of your new specification. Note that you can change these values later. For instance, if you wanted to switch v1 to v1.1 at a future point, the only place you’d need to change it is here, in the schema.

Figure 7.4. The Anypoint RAML editor features a bottom toolbar for adding sections to the schema model. This toolbar is context-sensitive; it will only offer appropriate sections based on where you are currently in the schema.

Figure 7.5. At this point you’ve added all of the resources for this schema. They are listed with a displayname, but none of the requests or responses is represented yet. This is a skeleton of the schema model you’re building.

Figure 7.6. Because you know what actions will be available at each level, you can add the methods and their descriptions to the schema model. This matches with the information listed earlier; at the list level (/toppings and /pizzas) you can GET the list or POST a new item. At the individual item level (/toppings/:id or /pizzas/:id) you can GET the item, PUT an update, or DELETE the item entirely.

Figure 7.7. Now that you’ve added the specific actions, it’s time to break them out and add specifics on how the requests and responses will work for them. The GET for the lists is a little bit more complicated than the GETs for the individual items will be, because you’re allowing the caller to search for a specific string.

Figure 7.8. The 200 (successful) response to the request for /toppings shows how the API will respond to a successful call. Because this is a JSON object, the top level is designated by curly braces, and the toppings item in the response is a list of the toppings in the system. The status pieces (success and status) reside outside of the list, as meta-information about the response.

Figure 7.9. The POST method at the list level (in this case, /pizzas) is described here. Because this is a write action, a body is associated with the request, and an example of that is displayed under example. A successful creation will result in a 201 response, with no body, and the 409 response is given if there’s already a pizza with the same name or id.

Figure 7.10. As you created an example request body for the POST section, you’ll need to include an example response for GET requests. The information shown here is for the /pizzas/:id resource, which returns information for the single pizza being requested. Although a 404 response isn’t necessary in a schema model (it always represents a missing item), it’s included here for completeness.

Figure 7.11. The PUT entry for an existing pizza (at /pizzas/:id) has an example request body and multiple potential responses. 204 indicates that the pizza was updated successfully, and the 4XX responses give descriptive error messages so that the caller knows what went wrong.

Figure 7.12. The final method for the /pizzas/:id resource is a DELETE, to remove a specific pizza from the list. In this case, no body is required for the request or a successful response—either the pizza exists and is deleted, or it doesn’t exist and a 404 response is sent.

Figure 7.13. The queryParameters section allows you to add different optional (or required) parameters to the GET request. In this case, there’s a q variable that indicates that the caller wants to search for a particular string in the pizza name (like "Maui"), and the topping variable requests a list of pizzas with a particular topping on them, using the topping id number rather than the name.

Figure 7.14. For the OpenAPI (previously Swagger) model, the metadata is slightly different. More of the information can be added at the top of the model, such as the content-type for requests and responses, the base path (separate from the hostname), and what schemes it accepts (http or https, or both).

Figure 7.15. The formatting for the GET behavior is different than in the RAML document, but comparing them side by side you can see that the included information is the same. The structure is called out more explicitly (defining where there are arrays, objects, or strings), and this more explicit model is preferred by many people.

Figure 7.16. As you build the schema model in the Swagger Editor, the documentation will autogenerate on the right-hand side of the page. Again, the description and output are at a higher level than a specific example, so it’s easier to understand the structure. But you lose the ease of reading that comes with an explicit example.

Figure 7.17. The POST request, with all of the definitions for the pieces, ends up being much more verbose than the RAML example. Still, the request and responses reflect exactly the same information, so whichever one feels easier for you is likely to be the best choice for your schema models.

Figure 7.18. The POST documentation includes the body required in the request (again, only PUT and POST require bodies in the request). Under the responses you can see the successful Pizza Created response as well as the error (duplicate pizza name or id found).

Figure 7.19. The subresource GET description is also more verbose in the OpenAPI format, though it more explicitly documents the types and names of each of the values within the object.

Figure 7.20. Note that the OpenAPI description includes pizzaid as a parameter, even though it’s part of the path (/pizzas/:pizzaid). This is one of the differences between this framework and RAML; having it as a specific parameter means that it can be explicitly defined as a string that is required. There’s no functional difference, but you may prefer one over the other when reading through the schema.

Figure 7.21. DELETE is quite simple: it can be even more streamlined, as the 204 and 404 responses are the standard responses for a DELETE. It’s all right to assume standard responses, and include the responses that are different from the norm, or have specific error messages included.

Chapter 8. Design-driven development

Figure 8.1. In the waterfall development methodology, each step in the process is completely finished before the next section begins. The entire cycle from start to finish can take months, or even years, without any built-in review or reflection in the system. This doesn’t mean that waterfall development never has this kind of adjustment, but it isn’t inherent in the system.

Figure 8.2. The agile scrum board looks fairly arbitrary and temporary by design. A sticky note or small pinned paper can easily be moved around, from the Stories waiting for attention, into the To Do column, through the additional columns, to Done. There’s nothing keeping a task from moving backward when the situation demands it, from Testing back to In Progress, because something didn’t work correctly, or from To Do back to Stories when other priorities emerge. This agility is at the base of the “agile” project management method.

Figure 8.3. When tests are written before the code is written, the expected behavior is expressed before an implementation can emerge, and the resulting code is much more likely to behave as expected. Tests are a great way for a team to communicate what they expect the functions to do within the system. For each test, only enough code is written to make the test pass, and then the entire test suite is run to make sure that everything still works as expected. This is repeated until all the tests succeed and the programming work for the project is done.

Figure 8.4. The BDD cycle incorporates TDD into a larger cycle of behavior-driven, or use case–driven, tests. These integration tests express what the system as a whole needs to do, which helps keep holes from developing between individual units of the product.

Figure 8.5. Ideally, API project management includes the development of a functional specification in parallel with the schema model. Only once these two documents have been completed should the acceptance criteria be written and unit tests developed. After all of this infrastructure is in place, the development iterations can begin. Although this seems like a huge amount of work up front, it reduces the amount of development time significantly—and more importantly, it reduces the chances of incorrect work that would need to be redone.

Figure 8.6. The original toppings from chapter 2. As you probably recall, the page itself is making a call back to the /toppings endpoint and processing the returned JSON to create this user interface. To see this in practice, use the Chrome browser and watch the network traffic to see how the JSON relates to the resulting HTML page.

Figure 8.7. This live server response represents what you’ll see in the Chrome Network tab when the initial user interface page in figure 8.10 is generated. The CSS and HTML pages are used to create the single-page application based on the back-end API response.

Figure 8.8. This looks exactly the same as the live response, but it’s the OpenAPI mock server responding with the information from the schema model. Responses from a mock server won’t change (so if you delete a topping it will still appear). Nonetheless, these servers are an excellent way to create a prototype or demo application to test and make sure the schema will support your use cases.

Figure 8.9. In this case, the mock server is running on port 8080 on the localhost, as you can see from the host entry. The schema model here is the same one created in chapter 7 and should in fact meet all the use cases identified in that chapter.

Figure 8.10. When running a mock server using the OpenAPI tools, you also get an interactive console to explore the endpoints and see how they work. This functionality is also available for the live server when it’s created. When you’re sharing the schema model with other developers or customers, sometimes it’s helpful to give them a visual way to explore the platform.

Figure 8.11. This call to http://irresistibleapis.com:8080/v1/toppings/ is accessing the mock server and is returning exactly what the schema model indicates. Again, if you make a call to add a new topping, update a topping, or delete one, this call won’t change, because there’s no live service on the back end but only a static model.

Figure 8.12. Along with the interactive console for exploring the APIs, there’s also interactive documentation created by the OpenAPI system. This is the same documentation you’ll be able to provide to your users when the API itself is live—which is one of the reasons to make sure that the API itself stays in sync with the schema model.

Figure 8.13. The process for pushing your model and server to Heroku is relatively straightforward, and it gets easier after the first time. All you’ll need to do is edit the files and push them back out to Heroku. In this case, the server infinite-basin-6068.herokuapp.com was created, and now the documentation and mock server are available on the internet to share with other people.

Figure 8.14. The standard agile storyboard format is easier to understand with an example. It can often feel forced, but having all three sections of the story makes it much easier to ensure that the requirement is well defined, and there’s a shared understanding of what needs to happen in order for the story to be done.

Figure 8.15. A scrum planning board generally has the same columns: a Story column for backlogged stories and tasks in the To Do column. As tasks get assigned or selected by team members, they’re put into the In Process state. Once they’re ready, they’re Verified by a different team member, and finally they’re moved to Done.

Chapter 9. Empowering your developers

Figure 9.1. The four pillars of API support are communication, documentation, building blocks, and support. Every one of these pillars improves your client developers’ understanding of the platform, and with that understanding comes engagement and integration.

Figure 9.2. Documentation takes many forms, and it’s critical to understand that reference documentation—what each endpoint does, and what the requests/responses look like—is only the beginning. Developers need to understand workflows for complicated chains of requests, and tutorials and guides are also critical to helping them understand the entire system more clearly.

Figure 9.3. Getting an Akamai Billing Usage report from scratch can be somewhat daunting. You need to call three different API endpoints to get specific information in order to make the final call. Creating sample code or documenting workflows can help users get past this type of challenge with minimal frustration.

Figure 9.4. The Apigee console for exploring the Twitter API lists the most common endpoints in the Twitter API, making it easy to understand the breadth of information available via the platform. The authentication can be activated to use your Twitter identity, using OAuth, so that the API responses are exactly what you see when accessing Twitter directly.

Figure 9.5. For the Twitter API, there are example calls for the majority of the Twitter endpoints. Selecting one of these demonstrates what the request and authentication look like, and how the response is formatted.

Figure 9.6. The Apigee generic console can be used to call the /toppings resource from irresistibleapis.com, making it possible to see all of the request and response information in an easy-to-read format. This enables you, or your users, to easily explore and understand the various endpoints.