What do you want to learn? Leverged jhuang@tampa.cgsinc.com Skip to main content Pluralsight uses cookies.Learn more about your privacy Creating Web APIs That Developers Will Love by Kirsten Hunter Web APIs enable organizations to provide a usable interface for mobile, web, and other third-party applications. This course will give you the knowledge you need to create a strong and vibrant platform. Start CourseBookmarkAdd to Channel Table of contents Description Transcript Exercise files Discussion Recommended Course Overview Course Overview Hello! My name is Kirsten Hunter and I'm excited to welcome you to my course on Irresistible APIs. I'm an API Evangelist at Akamai Technologies where I help our customers learn to use and integrate with our open APIs. I've worked with web API platforms and their developers for over 10 years, providing me with tons of insight into the frustrations and challenges many people have when integrating with APIs. I frequently speak at industry conferences on the topic of APIs and developer experience. In addition to this course, I've written a book called "Irresistible APIs", which is another great reference for this topic. In this course, you're going to learn the keys to crafting a successful API. The main driver for API success is a phenomenal developer experience and this course will give you what you need to really make that happen. Some of the major topics covered are Guiding Principles for API design, an overview of HTTP and API concepts, Schema modeling using RAML, a design process for crafting a compelling platform, and the keys to great developer support. You'll come away from the course armed with a powerful set of tools and knowledge to help you create a successful and engaging API. Course Overview: Building Successful APIs Course Introduction Over the past several years, web APIs have become increasingly popular. Using the available development frameworks, it is exceedingly easy to create a web API for your organization. Unfortunately, it's equally easy to create an usable API by skipping planning steps during creation. This course will guide you through the steps needed to create an API that's usable and successful. A popular web API will be easy to use and understand, fun to implement, and sustainable. In order to achieve these goals, you must define your business value, determine the metrics to track success, and create use cases describing how you want developers to use your API. An API that is unusable and poorly planned will be hard for client developers to understand. This API will additionally be challenging for those developers to implement. When an API has these issues, your team will suffer the effects of a high-support burden, as your customers reach out to get help working with the platform. One of the main reasons for starting with the business value is that you must get support for your API at the executive level of your organization. Management needs to be able to clearly understand and articulate the value your platform will bring to the company, and how the metrics will be used to demonstrate progress. In addition, the development team needs to understand the use cases guiding design and development in order to stay on track with the creation process. This course is designed to help you create a usable and successful web API. Working through the modules will help you create great APIs, by designing and developing APIs that developers will love. This process will ensure that you end up with an A-list API that attracts and retains developers. I'm Kirsten Hunter, and I'm excited to invite you to my course on creating web APIs that developers love. Course Overview Course Overview, building successful APIs. This module is going to detail what the course covers from beginning to end. Topics included are as follows, API basics, what is an API, and what are the advantages to web APIs? API-First, this best practice standard will help you to create a stable and maintainable system. Business value, why do you have an API, and what are the potential benefits to your company? Metrics, how will you determine the relative success and progress of your API? Use cases, what do you want your client developers to do with the API, and how do you make these use cases easy to implement? Schema modeling, laying out the structure of your API before coding allows you to ensure consistency, and discuss the API with your customers and developers. Behavior driven development, developing based on the use cases you want to support, and using those use cases as test cases for the project. Developer experience, making your API usable, and supporting your developers in order to ensure, engage successful customers. API Basics The first concepts I'm going to cover are API basics. I'll start with a high-level explanation of what an API is, the term itself stands for application programming interface and it refers to a computer system interface which is designed for easy interaction with other systems. Unlike more traditional systems which are tightly coupled, and thus hard to extend, web APIs are designed to make it easy to connect different systems together. In order to be complete, an API must allow users to create, read, update and delete items in the system. The mnemonic used to detail this requirement is the delightful term, CRUD. Historically, APIs have been used for computer systems to interact closely with each other. For instance, the database might work with a finance system in order to create billing reports for the finance team. This interface may not work gracefully for other integrations, sharing the functionality is more difficult. This reduces your ability to extend the functionality to third-party developers or other applications, or even to your partners. Another big disadvantage is that changes on either side of the connection need to be managed quite closely, as the functionality is tied together at a fairly low level. On the other hand, with web APIs, you can have developers working to integrate dispute systems together, using a well-documented and stable interface, so its external developers can integrate with the system fairly easily. You likely use systems incorporating APIs everyday. The Facebook "like" button you see on news sites and blogs uses Facebook's API. When you log in with Twitter, you're using Twitter's authentication API. Fitbit's API is used to interact with several other fitness applications and devices. The Twitter stream you see in other applications gives you a view into your social feed, even when outside the Twitter application. Each of these provides a way for you to interface with a system when you aren't directly connected with it. This is one of the huge advantages of web APIs, extending the use of a product outside of the main system. To understand HTTP itself, let's put it into the context of web browsers, the most common use of the HTTP protocol. When a client, such as a browser, makes a web request, that web request has two pieces. First there is the URL that you type into the browser window, that is the noun, or resource you want to access. When the browser makes the request to the system, it will indicate that it wants to read the specific object. When you submit a form using your browser, that browser tells the server that it wants to create a new resource, the information that you've sent from the form. This can be illustrated better with a real-world example, such as the interaction between a customer and a cashier in a coffee shop. In this case the customer is acting as a client application, and the cashier is acting as the server. When you request an iced tea you have created a new item, an order, adding options to this order, such as extra ice, updates that item. When you ask the cashier to tell you what you've ordered, you are performing a read of your order. And if you've accidentally left your wallet at home and have to cancel the order, that item is deleted. There are more complex factors to this system, but this is the essence of a web API transaction. While there are multiple different types of web APIs, in this course I will be focusing on REST APIs, a particular type of implementation that has become the most popular choice. REST APIs focus on nouns, or things, rather than actions. This means that instead of using the API to call a particular function, the client application operates directly on the resource, which is the same, regardless of the action being taken. There are several advantages to using a RESTful web API. It exposes the data in the system as objects for interactions between the client application and the platform. Binding code where the systems are separated by a documented interface protects both from unexpected changes. It is easier to test a web API which has a documented interface, and it helps to protect your internal methods from unexpected use. API First API-First is a relatively new concept in the API industry, and it describes a best practice which will ensure quality and consistency for your API, as well as providing a more agile and successful development process for your main product. To help you understand API-First, and how it differs with historical API development, I'll describe how APIs used to be created. The backend, or server, was tied directly to the frontend system. Database calls were made directly between the two systems, and they were coupled quite tightly together. Changes to either one required very careful planning in order to maintain stability and functionality. APIs on the other hand grew out of the side of the backend server, providing a different interface into the same information. This caused duplicate code, which is always a bad idea, inconsistency in resources and representations, feature inequality, and overall frustration for customers looking to use the APIs for applications. Whether those applications were your own mobile apps, or someone else's integration. APIs are truly a second class citizen in this scenario, and it's not a great setup for success. On the other hand, with API-First, the backend system exposes data through a single set of APIs. Each of the client applications, including the main product, consumes their information through this set of APIs. The APIs are thus robust, tested and usable, and there's no reason to rewrite implementations in order to expose functionality to API clients. API-First creates a much more sustainable and usable system, and it encourages the company to consider the API as a core part of the product line, a first class citizen which makes the other products better by improving their interface, consistency and reliability. Business Value The next part of the course will be on Business Value. Many times, an executive or development team will embark on the creation of an API, without determining why this API is important to the company, or what goals it will accomplish. Creating an API in this way generally results in a product with no cohesive vision. Metrics aren't created to determine success for the platform. A really difficult case arises where you're asked by the executive team why you have an API, and you're left without an answer other than Because, APIs! The API is never seen as having a consistent value for the company, and it becomes difficult to justify in the medium and long-term. So what is your business value? You may think that monetization is the right course, that you should charge customers to use your API and pay for the development in that way, but in most cases this is a poor choice. Charging customers for your API discourages them from using your API. When your API is well-designed, it makes your main product more valuable, and you want your customers to use it. Of course, for companies where their main product is run by APIs, such as Twilio and Sun Grid, this is not the case, but if you are simply making a new interface to your existing product, you should consider carefully before implementing a revenue model like this. On the other hand, customer stickiness is a strong candidate for business value for almost all companies, you want your customers to integrate with your API, because it makes them much more likely to stay. If you provide ways to automate processes, you can remove or reduce pain points for your customers and partners, as they're able to perform repetitive tasks automatically. Integration and automation both make it much more likely that customers won't leave, and it's a great value to share with your executive team. In my job as an API evangelist, I travel around the world and teach our customer developers how to use our APIs for free. It's the best job, because I'm telling customers that the products they've paid for are even better than they thought. Considering the business value is a critical step for any product, and your API is no exception. There are many other examples of business value and I'll cover them in more detail in that section of the course. API Metrics Metrics, like business value, require some mindful thought. Otherwise you'll end up with pretty graphs which are meaningless to the executive team, and add no value to the platform. The most common and poorest metric for an API is how many developers have keys for your API? This doesn't even measure how many developers have successfully made a call to your API, and is more a measure of your onboarding process than anything else. A decent thing to measure as a small part of your success, but certainly not a great metric to focus on. Similarly the number of API calls seems like a better measurement, and it is, but it's still really not granular enough. You could have a million developers making a single call and then giving up, or 100 highly valuable partners each making thousands of valuable calls daily to drive their applications. Determine what kind of calls you want your customers to make and use that to help you determine what metrics to use. Are the developers using the API in a way that moves the platform forward, and increases the value of your main product? If so, that's what you should be measuring, not general call volume. So we need to come up with some strong metrics to support your business values. Do you want your partners to integrate with your API, increasing usage? Take a look at the number of different calls your customers are using, and see if they reflect the goals of your platform. Whether it's allowing users to search your database, or viewing user profiles, you should be able to see strong usage across the board by your partners, rather than sporadic use or unwanted behavior like database scraping. A great metric for most companies is the number of users accessing the platform via the API, and how they're using it. If your customers have different ways to access your product, they're likely to interact with it more times each day, in different ways. This'll increase your users' loyalty to your product, and increase the perceived value of your main product, a great goal! Finally, each partner or customer should be increasing in volume over time, if they're appropriately integrated, and measuring this will help you to determine which of your APIs are most valuable to your customers, as well as showing the executive team where developers are leveraging APIs to improve the customer relationship. Think carefully about what your business value means to you, and how you can reflect that in metrics. Remember, your API is just like any other product, and you need to be able to communicate value and improvement. Knowing what your metrics will be will help your product team achieve success, and communicating it with your customers will help them to work with you, to make sure they're aligned with your goals. Use Cases Once I've helped you determine what success will look like for your API, I'll turn to covering the job of creating the API to meet that goal. The next section of the course will be on use cases, what things your API should make simple and smooth for your customers. This may seem unnecessary, but when you dig in a bit, you'll see that this part of your plan also needs careful thought in order to ensure your success. This is one of the hardest things for product teams to remember, that building an API should be done from the top down, with the user in mind, as opposed to building it up from the backend. It's frequently a good idea to tackle your main product as a set of use cases, it may seem like overkill, but you'll want these ready to use when you want to add new functionality to your platform. Customers and partners will frequently ask for features that your main product has, and if you've already considered them, it'll give you a leg-up on understanding how much work it will be to implement them, and understand how the functionality may converge with other use cases you've already implemented. From here, you can determine what a minimum viable version will be. What is the core of your technology? This is one of the best sets of use cases for you to start with, and will act as a springboard for the other features. Also, what features will make sense to add later? Or alternatively, what do you want to have before you release your API to your customers? Next, a great place to focus is on a mobile application. Whether you have one or not, you can take that minimum viable product and see how it would work for mobile developers. Note that mobile is really critical to examine, because the needs of mobile developers are different than web developers. For example, they require that all the information for a single screen be available with a single call, and want the data to be as small as possible to ensure a performing application. A basic mobile application is a great way to focus on the main features of your application, and ensure that you've really nailed the minimum viable product. Your partners and customers are likely to want to integrate with your application in multiple different ways, I'll cover these in more depth in the section on use cases, but for now, let's look at a few different things customers might want to do, things which should be simple and easy to implement. First, automation is frequently important to users, especially when there are tasks they want to be able to perform frequently. For instance, at Akamai which is a content delivery network, are a huge cache for customers. Our users frequently want to be able to clear the cache for a specific file, or files. Making this available via the API is much easier than having them push a button on a webpage. Automating tedious tasks in this way is a great feature for your platform. Next, if you have configuration or update features for sections of your API, these should be easy, and it's particularly important to be clear about how they work, and test your decisions by talking with your internal or external customers. Anytime a customer is making changes to the system, the process should be clear and streamlined so they don't accidentally make unexpected or unwanted changes. Another area to consider is alerts. If you make it possible for your users to trigger actions based on alerts, it'll make it much easier for them to integrate more completely with your system. Whether it's a subscription for feed updates to your social application, or system alerts from your server farm, making it possible for applications and systems to integrate with these important events will really improve the user experience with API-driven applications. As you can see, development of use cases is a critical part of the process of creating APIs that are easy to implement and use. Avoiding the frustration of using inefficient APIs will reduce your support burden, and decrease the chances of your users using your API in an unsupported or unexpected way. Schema Modeling In the next section, I'll talk about schema modeling. In the past, action-based APIs were very explicit. An application would request a contract from the platform, and receive information about what calls could be made and what they would return. With the move to resource-based APIs, these contracts are no longer used, because it was expected that companies would develop APIs that were consistent, easy to use and well-designed. Unfortunately that's not exactly what happened, and so schema modeling has sprung up recently as a way to map out what your API does, and how requests and responses work. Additionally, the APIs from a company frequently come from multiple different departments, and so it's a challenge to make sure that they're all consistent with each other, and to ensure that it is easy for developers to move between the different functions. In order to impose some kind of consistency, and enable ease of use for developers of all of the different features, a schema model creates an artifact which can be shared with your product managers, other developer groups, and even your customers, before you even write a line of code. While developers may be resistant to this kind of process, they want to get started right away, they will appreciate the end-result, which is that it's much less likely they'll need to rewrite that code when the platform is finished. A schema model is a map of all of the endpoints of your API, and describes what each one does, what the requests will look like, and how responses will be formatted. It can be used for development planning, testing, mock servers, and all of the main schema modeling frameworks also provide some amount of free interactive documentation, a great feature which reduces the need to create one of the main documentation requirements, and allows the team to instead focus on use space documentation and guides. A schema model will additionally help ensure consistency within a particular API, and across different APIs from all areas of a company. Thus, for instance, a user resource from a finance API would be represented exactly the same as a user on the profile API. Additionally, this kind of document is a great tool for communication. It is understandable by non-developers, and can greatly improve the understanding of the API before development begins. Additionally, sample clients can be created to demonstrate functionality using a mock server, so you can show exactly what the API will be capable of, and catch required changes up front. In the module on schema modeling, I will cover a couple of the main frameworks, RAML and Open API, and demonstrate how to create a schema model for a basic API. Design-driven Development The next section of the course focuses on design driven development, using the ideas you created to develop your API from the outside in. For most of the history of software development, projects were developed using a waterfall model. The functional specification for the whole project was created, and then engineers would go heads-down to work on development in cycles of several months. Releases were large and impressive, but there wasn't much opportunity during development to adjust to new requirements, or change troublesome implementations. Adding new work was difficult to estimate and could easily result in missed deadlines, so new features or requirements were less likely to be implemented in a timely manner. Pivoting your product in a new direction based on new company needs was much more difficult as well, and projects could be obsolete or off-message before they were completed. This frequently resulted in major refactoring of the product after the first development cycle was done, pushing out the needed changes until the end of another long development cycle. The Agile development cycle, which has recently gained popularity, still has large stories or goals, but development cycles are short. Agile development is sometimes considered almost a religion, but it's better to consider it as a buffet of ideas, from which you can choose the model that best fits your company. Within the Scrum model of Agile development, large products are broken down into smaller stories, which are in turn broken down into tasks. These tasks each move from a parking lot, where needed stories are stored, into a to-do list for the sprint, onto an in-progress status, and then to verification, and finally completion. This model provides a much faster sense of gratification, and a Scrum storyboard provides a great visual tool for the team to track their work, and communicate with other interested parties. In Scrum, a project is broken down into iterations of one to two weeks, rather than the longer waterfall development cycles. Planning in retrospect of meetings assist the team in making sure that they're still on target for the larger stories, and daily stand-up meetings of 10 to 15 minutes help the teams stay on track during the sprint. All of this makes it easier to adjust the project as needed when new requirements arise, or existing stories change. Making smaller, tuned releases makes a much better cadence for the customers, and more motivation and satisfaction for the engineering team. Taking the idea a bit further, let's discuss design driven development. The stories are based directly on use cases, and those use cases are used as your final integration task to make sure that your project has achieved the desired goals. Sprints are still based on stories, as in Agile development, but the larger stories are directly tied to the functionality you're planning to provide. Again, this development is from the top down, instead of from the bottom up. Delivery of the functionality can be clearly described and documented for customers, so they understand exactly what they can now do and implement. Developer Experience The final section of the course will focus on one of the main drivers for API success, the developer experience. As discussed in previous sections, the critical features of a great API are that it be easy, straightforward and usable. While many architects like to focus on reliability, security and scalability, remember, if you don't focus on usability as one of your top priorities, you're not likely to ever need to focus on scalability. When you come to the end of the development cycle, it's very tempting to think you're done with the API, but you still have some work to do. The most important piece of an excellent developer experience is great documentation. Of course, an API must have reference documentation that is clear and complete, covering all of the end points. As I mentioned earlier, this type of documentation is easy to create using a schema model. Many companies feel that this documentation is sufficient, but while it's necessary, it's certainly not enough to support your developers' needs. When a developer comes to explore your API, they don't just want to know what the end points do, they also need to know what they can do with it, and how exactly to do those things. In order to support these needs, you need to have good tutorials and guides for your developers. It's especially important to have a "Getting Started" tutorial, so they know how to make that all-important first call to the system. Along with this documentation, you need to provide as much sample code as possible. Developers love to play with existing code that just works, so they can try different things, and work from something without having to struggle to get started. Remember that developers love to build things, and help them to do this as easily and quickly as possible. In summary, here are the areas which will be covered in this course on building APIs that developers will love. API basics will give you a great foundation for the rest of the course. The section on API-First will give you a good understanding of the best overall architecture for your platform and main product. Determining your business value is key to your platform's success, and this section will help you to do just that. Metrics will support that business value by helping you measure progress toward the goals you have identified. Use cases are key to making sure that your API supports these metrics and business value. Creating a schema model is valuable in helping to map your API before development has started, so you can then ensure that your product is successful the first time. Design driven development focuses your product goals on the use cases you identified. And arguably the most important section is on developer experience, if you can create an amazing experience for your developers, you are well on your way to a successful API. Understanding Web APIs Introduction In this module, I'll be covering the interaction between HTTP client, and server in detail, and help you set up and run an API server on your own system to explore those interactions. The sections for this module include, Module Setup, where I'll cover the crown browser, as well as how to install docker and the module code on your local system. If you're already familiar with HTTP basic concepts, you can skip the sections covering the protocol and go directly to the API sections. HTTP Interaction describes the basic structure of HTTP transactions, including the requests and responses. HTTP Methods, covers the four most common HTTP verbs used for rest API's. HTTP Status Codes, a high level description of common status codes and their meanings. API Engine Setup, running the API engine on your local system in order to work with it, and Exploring the API in a Browser. Module Setup To begin with, you'll want to gave the Chrome browser. If you don't already have it, please download it onto your system. Additionally, you'll need to have Docker installed on your computer. Why Chrome, Chrome is available on current operating systems. It proves fantastic developer tools, using these developer tools, you can watch both the front-end traffic, and the back-end API traffic driving a single page application. Any time a website is making requests on the back-end, it's quite useful to see what that traffic looks like so you understand what the requests and responses look like. As we look at these things you'll start to understand more about the real world applications and how they relate to the API fundamentals I will be talking about. There's nothing like playing with technologies directly to really cement these concepts in your mind. Why Docker? The newest version of Docker is available on current operating systems, such as El Capitan, and Windows 10. While it takes some time to download, it's worth your while to get it. Because of the way the Docker container is configured, all of the setup for each of the languages is done during the container setup. The container is created from the Github repository so you're always pulling the most recent changes and additions I've put in the system. If you've used the Docker machine, or boot to Docker systems in the past, you may have found it to be somewhat cumbersome to work with a virtual machine with a different IP. But the current native clients share the same IP local host, and it's quite easy to work with for local browsing of web services. These clients are available for the most recent version of OSX and Windows 10, and older operating systems are supported with the older Docker toolkit clients. Go to https://www.docker.com and download the native Docker client for your system. Docker has excellent documentation on their site to help you to get up and running. If you have an older version of the Docker engine, it's definitely worth it to get one of the new native clients if they're available for your operating system. Go ahead and do that now, and when you're done, you'll be ready to move on to the next section in the module. HTTP Transactions To understand the transactions between an HTTP client and server, and API interactions, you'll first need a basic grasp of how HTTP works. Here's a high level description of what's happening. HTTP stands for HyperText Transfer Protocol, you're probably most familiar with this protocol as the method browsers use to retrieve webpages, the browser makes a request to the server, and the server responds with a content to display on the browser. Every transaction is composed of a request and a response, HTTP is stateless, which means that each interaction is considered separately from any other transactions. Let's take a deeper look at how transactions are structured by walking through a simple browser interaction. Open your Chrome browser. Let's turn on the developer tools to get more information about the interactions the browser is having with the server. Under the View menu, select developer, then developer tools. Extra information about the transactions will now appear in the developer tools as you use the browser. Enter https://irresistibleapis.com/demo in the address bar. As you can see, in the developer's tool panel on the right, the files which have been requested are listed. The original request is included, as are a couple of back-end API requests which we'll cover later, and style and java script files. This is a great place to look to understand the structure of an HTTP transaction. Click on the top entry in the resource list in the panel, several tabs are available to provide basic information about that transaction. Click on the Header tab. At the top of this section, general information show the basic information about the request and response. The request URL itself is showing first. Next, the method for the request is displayed, every HTTP request has a method associated with it. In this case, GET is used. The status code is also displayed, a 200 OK. Just like every request has a method, every response has a status code. I'll cover the various possible status codes a bit later, but for now it's sufficient to know that this means that the request works successfully. The IP address of the server is also displayed. The rest of the information displayed represents the headers for the request and response which I'll also touch on shortly. HTTP Methods HTTP Methods. There are several accepted methods or verbs used within HTTP. The most common methods map directly to the operations needed for a complete system. The delightful mnemonic used for the actions the system needs to support is CRUD, for Create, Read, Update, and Delete. It's important to understand the distinctions when thinking about API design, as you want your API to work as people expect, and the method used is one of the fundamental pieces of the HTTP transaction. GET is a simple read operation used to request the current information for a resource on the server. It's the most common verb used for HTTP transactions as browsers are generally using GET for their requests. You can perform a GET at whatever level makes sense, so you can get information about a particular item or get a list of items. PUT is usually used to update an existing resource on the system. So, if you have a system for customer's orders, you might this to add another item to that order, or change the address associated with it. PUT is generally not used to add new items to the system, a PUT usually operates on a specific item in the system, not on lists of items. Although, in some cases, a list can be updated all at once by performing a PUT with the entire new list of items. When PUT is used, the expectation is that the data being sent to the system represents the entirety of the item being updated, not just changes that are needed. There is another verb, PATCH, which is sometimes used to change specific pieces of an item but it is not in wide use at this time. POST is generally used for adding new items. A very common pattern, is to have a client send a post to a list of items to create a new item on that list. Once the item is created and has a unique identifier, PUT would likely be used to update that item. As with PUT, the entirety of the item is sent to the system at once, and the system responds with the unique identifier, or URL, for the newly created item. When you fill out a web form and press the submit button, the action your browser performs is usually a POST operation. Some older API's needed to use POST for alread actions, including create, update, and delete, because there were clients such as Flash, that weren't able to send requests using HTTP methods other than GET and POST. But thankfully that's no longer the case, modern clients can send the four main HTTP methods and requests, and it's really best to use them in this way. DELETE is the easiest method to remember. A DELETE on the specific resource removes it from the system. The DELETE is done at the resource level for a specific item, not on a list. If a DELETE were supported at the list level for an API server, the client could reasonably expect the entire list would be deleted. Think of it as the difference in removing a topping from a pizza, versus removing the pizza entirely. HTTP Status Codes Just as each request has a method to indicate which action the client wants the server to perform, every response from the server has a status code associated with it. The HTTP status codes cover a wide range of messages the server can pass back to the client to indicate what happened on the server side. These messages are three-digit numbers grouped by hundreds into various buckets. Speaking on behalf of the server, a 500 response generally means we messed up. The most common 5XX response, is a 500 server error. This can happen when the server is overloaded or when you tickle a bug in the server implementation. A well-designed API should rarely run into 500 errors. If you have sent information in an unexpected form, the system should determine that upfront, rather than passing it to the server and receiving an error. In many cases, the issue is simply that the server is over capacity. For this reason, it's often reasonable to send the request again after a brief delay to try again. A 4XX response usually means that the client messed up. 4XX responses cover a wide range of error types. Common 4XX errors include authentication, authorization, or missing content. An authentication error means that the system can't identify who you are, and these return a 401 error code. Authorization errors mean that the identified client doesn't have access to the requested resource, and these will return a 403 error code. Missing resources return a 404, and you've probably seen these quite frequently when browsing the web. There are specific status codes indicating missing parameters, rate numbering issues, incorrect content type, and multiple other client issues. A 3XX response means, go ask that guy over there, it points you to someone else. 301 means that the resource has been moved permanently, and it's a signal to the client that future requests can reasonably use the new URL when accessing that resource. A 302 means that the resource has a temporary new location or URL. This is frequently used for resources which might move frequently, where the system is designed to expecting you to continue using the same entry point to find it. These redirects should be followed to the new location to find the resource, but the client should continue using the original path when accessing that end point. A 2XX response indicates everything worked correctly. These responses are pretty straight forward. The most common status codes for a read request is 200, which means that the request was successful. So when designing an API, it's really helpful to leverage the ridge set of status codes available to help your clients understand how to fix issues when they occur. API Engine Setup Let's get started with a hands-on example to work with directly, so you can get a feel for what's happening with a full-fledged API engine. In this case, you're going to be working with an application stack I've created to demonstrate basic API server design. The fortune cookie application, is a single-page application which interacts with an API engine, which in turn interacts with a Mongo database on the back-end. I'll demonstrate the functionality using Node.js, although there are other languages in the repository to explore. There are examples in Perl, Python, Ruby and PHP, if you're more familiar with one of those languages. You're free to spend as much time as you like exploring each of them. On the back-end, the data is stored in MongoDB, a no-sequel database engine. The API manages a list of quotes, stored as author and content, along with an index for sorting and organizing. The API and included single-page application allows you to create, read, update, and delete the quotes in the database. Note that this particular setup is simple by design, the goal is to show you how to interact with a simple API directly. The single-page application is just there to help you see how an application interacts with the rest API. There are a couple of different ways to set up the application stack. For this course, I'll cover setup using Docker, although, if you're more comfortable developing on your system natively, you can set up the system using Github. The instructions for a local, development setup are included in the README file in the Github repository, which can be found at the address shown here. The first step to getting the Docker container running is to install Docker itself. If you haven't already installed it, go to docker.com and install the engine for your particular system. Once you install the engine and it's up and running, you're ready to grab the container for this course. This can take some time the first time you do it, but once the container is pulled on to your system, the command is basically instant. I'll go over the command you need to follow here, and then I'll go through the process live so you can see how it works. In your terminal or command prompt you're going to pull the container. This slide shows the various pieces of the command itself. First, of course, is the Docker command itself followed by the run sub-command. This sub-command tells the engine to pull the container and then run it live on the system. If you haven't already pulled this container on a previous pass, we'll pull it from Docker hub and then run it locally. This can take several minutes for the first pass depending on the speed of your network connection. This command is essentially pulling a new copy of the virtual machine onto your system, so it can take a bit of time to get that done. The -i flag tells the Docker machine that you want to run the container interactively in a show, and then -t flag tells it to run in a pseudo-terminal as if it were attached to a display. The -p 8080 flag instructs the engine to map-port 8080 on the container to port 8080 on your local host. Since your local host in the Docker container share an IP address, this means that you'll be able to easily access the web server using a browser pointed at your local host. By default, Docker doesn't share ports outside of the Docker environment, so this command is necessary to allow your browser to use the webpage. The final piece, synedra/polyglot, names the container you're asking it run. This container is housed on Docker hub, where the machine will look for containers which aren't available on the local system. Now let's got through the environment setup together. First, I'll pull the Docker repository in the terminals to start up the environment. Now that it's started up, you can see on the screen ahead of you, the commands that you need in order to populate the database, so let's do those now. Starting up the database first, and then I'm going to go ahead and copy and paste the command to grab the quotes, quoteid.json file, and populate the database with. So as you can see, it's imported the information into the database. Let's take a look at the directory at the base of the container. So, in the container, there are various files the Docker files describes the Docker file itself, MOTD is what we say when we started, README.md gives you information about how to start it up if you don't want to use Docker. The data directory has information for the data, mongod is the script in order to start it up if you're running it locally. The static directory and the schemas directory are used just for information about the system. But each of the other directories represents a particular programming language that you can run the engine in. For this course, we're just going to use the node example. So cd into the node directory, and do node express-server.js, and go ahead and leave that window running, and then we'll go over and check, take a look at it, in the Chrome browser. Browsing the API Using Chrome In this section you're going to use the Chrome developer tool to see and understand the traffic between the API traffic and the front page application. To start, simply point your browser to http://localhost.8080. As you can see, you've got a nice welcome message from the system, indicating that it's running the express server using node. Let's start at the Chrome developer tools again so we can really see what's happening here. Go to View, Developer, Developer Tools, to bring up the developer tools pane. It's a little hard to read what's going on in this page, so I'm going to go ahead and change to view, actual size, so we can see what's actually going on. Let's refresh the page, and now on the right-hand side, we can see the request that was made, local host, you can see that it's exactly what you requested, localhost.8080, we had a GET, a 200 OK, and the information was sent as text html. So on the server, you're running with the back-end Docker container that we set up, you can also see the quote server. So go to API, quotes, you can see here the first 10 quotes in the system, it doesn't show all of the quotes because we're trying to keep it from sending back too much information. If you click on the quotes in the resource bar, you can see that in fact this was actually sent as application json. If you go to response, you'll see that it is the same information that was sent in the page, it's not styled in any way because it's json and not html. Now, let's take a look at the demo application, the single-page application that we have for the front-end application. So it's localhost.8080/demo. Now, as you see on the right-hand side, we do have some styling that was sent, and we have some java script for the actions that are happening on the page, and we have a random quote here, but let's take a look at quotes API, you can see that it is the same thing that we got back from the original request that we made to API quotes. It is exactly the same information. Now, this page allows us to interact with the system, we can do things like viewing a particular quote, you can see that the call made it back directly to the 2000 quote, but that's not what we're actually interested in, that's something that we can do pretty easily. What's interesting here, is that if you go to the demo page, and you click delete, you can see over here that we had a delete request that was sent back to the 2000, and now the quotes no longer shows that 2000, that quote has been deleted from the system. So using the developer tools, allows you to see the interactions with the system, you can see that the call was made, this allows you to create, read, update, and delete items in the system. So now that you have an idea of how that interaction works, go ahead and play with this some more, you're not going to hurt anything, this is just on your local Docker system. And you have the information you need in order too start designing a well-created API. Defining Your API Guiding Principles In this section, I'm going to discuss defining your API. These are the guidelines and steps you'll want to consider and complete before starting the technical design and implementation of the API itself. This module will cover the following topics: Guiding principles, the most important things to remember as you move through the process of API creation. Business value, determining why you have an API and how it will contribute to the success of your business as a whole. Metrics that you'll use to track the progress and success of your API over time. And use cases, the all important stories that will guide your design and development and help you create a successful, engaging API. While going through the process of creating an API, there are many different principles to consider. Don't think of these as checklist you go through once, but rather, important ideas you should keep at the top of your mind while you move through the process. Think of these like the rules for driving a car. You need to check your mirrors each time you back up or change lanes. Doing them one time doesn't mean you shouldn't be mindful of them in the future. With that in mind, let me cover a few different thoughts that will help you to create APIs that are successful, engaging, and usable. First, and most importantly, don't surprise your users. Be trustworthy. Extend your API where needed to support use cases. And focus on those use cases as you're creating the API. Don't Surprise Your Users Meeting the expectations of your developer customer should be one of the top priorities as you move through the creation process. There are a few ways you can can surprise your users in a bad way, and avoiding this will help guide you to a truly irresistible API. I'll cover a few different ways users can be unpleasantly surprised to help you avoid them in your platform design. First, always aim to follow existing best practices rather than striking out on your own to create new techniques. Emphasize the developer experience of the people using your API, rather than those creating it. And strive for consistency throughout the platform. First of all, let's talk about your developer customers. Existing APIs are frequently designed with the notion that since APIs are interaction between computer systems, the interface doesn't need to be designed carefully, as long as it's functionally complete, it'll work great. However, and here's the thing, developers are people too. The developers writing code to consume your API for integrations and applications are your users and you need to respect their time and energy. Many developers who come to your site will have worked with other REST APIs in the past. They understand how to work with HTTP systems and understand the methods and structure of REST APIs. For this reason, it's usually best to stick with the best practices out there, not try to reinvent the wheel by creating a new way to interact with your system. It's often tempting to develop an improved interface, but remember, since the users are usually going to reside outside of your organization, you want to share as much context as possible with them. Even for an internal API shared with other groups at your company, it's important to make the learning curve for your API as quick and painless as possible. I've seen many APIs that use POST for all requests, whether read or write requests. This usually means that the system is more of a SOAP API, with a single endpoint to process all the information requests, but without the contract creating a shared understanding of the system. If your resources aren't represented by different endpoints and you're posting all of the calls, you're missing a lot of the interaction patterns your developers expect from a REST API. On the flip side, I've seen a lot of APIs that use GET for all calls. This is a horrible idea, as any web developer should reasonably expect that a GET request won't make any changes to the representation of the resource on the server. It sure makes it easier to develop the APIs but it invites mistakes in the clients accessing your system. There are of course some systems that use a combination of GET for read operations and POST for all write operations. This was needed ten years ago, when clients based on Flash or other immature web technologies weren't able to handle all the available HTTP methods. But nowadays, there's no reason to overload the methods in this way. One example where a company provides an API which does not follow RESTful principles is Flickr. Their API uses POST for all writes to the system and GET for the reads, but more importantly, the resources themselves are commands. It's like a SOAP API, except that commands go to different resources and each of those resources is a command endpoint to a method, rather than the object itself. Here, let me show you. As we can see, the endpoints aren't specifically related to the individual photos in the system. The POST method is used for all of the write calls and in fact, a photo is deleted by posting a request to the system. Deleting any photo is done by sending a POST to the same photo deletion endpoint. They have a REST endpoint, which is as unrestful as it could be. API.flickr.com/services/rest/method=method and name equals value. For each of these calls, regardless of whether they are read or write actions, all of the pieces are sent as GET parameters. Technically, a server should disregard all GET parameters for a POST request, but this is ignored here. Because of the way the interface works, you cannot GET and PUT to the same resource, as the retrieved object will be an XML or JSON and the write will need to be in parameter format. Additionally, Flickr uses non-standard error codes rather than HTTP status codes, as shown on this screen. Developers working with the Flickr system are thus required to learn an entirely new interface model. Each endpoint needs to be understood independently of all the other ones. There's no reasonable way to understand the system as a whole. And for errors, which should ideally happen infrequently, each error needs to be checked against the list to find out what kind of error has occurred. Note, one might argue that the Flickr error codes are more descriptive, but HTTP status code messages can contain a message usually formatted as JSON or however the response itself was expected to be formatted, specifying additional information about the status. Flickr does have a successful API despite the extremely poor developer experience. However, it's best to learn from the industry best practices and create a platform that works exactly as the developers can reasonably expect. It'll save you a ton of time and frustration on both sides over the long term. Consistency is also critically important. If your API works a particular way for one set of endpoints, but does something else with another subset entirely, your customer developers will be put in the situation where they have to repeatedly go through the process of learning the system and it will result in frustration and unexpected issues. Examples of this are using JSON for some resources but XML others, accepting write bodies as form encoded payloads versus directly sending JSON, providing different representations across different endpoints for the same object, or even having different representations for read and write for the same object. All of these may seem insignificant in the context of creating a single API endpoint, but taken as part of the whole platform, they can add up to a frustrating and complex developer experience. Be Trustworthy Be trustworthy. Today's developers have frequently interacted with multiple different APIs during their development careers and some of these companies have pulled the APIs off the shelves or significantly reduced the functionality with little or no warning. Sometimes API changes are made quietly, without announcing them to third party developers who are relying on the functionality. To understand why this is a problem, imagine the following situation. A developer has decided to create a third party application integrating with the company's platform. They put their time and resources into developing the application and they monetize the application and support it as a real product. Meanwhile, the API provider decides they don't want to support third party developers anymore. They drop support for the platform and slowly starve functionality away from the APIs. But they don't announce a change to developers relying on the system. Third party applications starts to fall behind the main product line in terms of features and functionality. The developer isn't aware that the platform has changed significantly and it's a poor experience all around. This has happened several times in the past, across the industry, and has understandably resulted in developers who are wary of trusting platforms, unsure whether these platforms will continue to exist, be supported and maintained, and get updated in line with the main product. For this reason, it's critically important to communicate clearly with your customers. The process I'm about to outline will include determining your business value, metrics, and use cases. I would argue that all of that information is just as important to the customers who will be working with your APIs as it is to you. Why do you have an API? What are you hoping to accomplish with it? This question will help guide the developer to understand what kinds of applications are likely to fit gracefully into your application ecosystem and which things are more off the beaten path. Just as you should be able to tell your CEO exactly why you have an API during an elevator ride, your API customers should know the same information, clearly and completely. How are you going to measure success? Another piece of information that's quite useful for a third party developer. They're invested in the success of your API and they're smart enough to know that the livelihood of the platform is going to be tied closely to however you're measuring success. If you're counting the times people write to the system, or different kinds of interactions with the system, share that as openly as you can. What use cases are you planning to support? Use cases can generate tutorials and how-to guides to help your developers understand how to work with the system and what you expect people to do with it. Not only do these use cases help you validate that your platform is enabling people to do what you want them to do, they're a great way to communicate how you want people to integrate with your platform. Similarly, it's very tempting to keep the schema and resource model secret, while developing your API and even afterwards. But remember, as soon as your API is released, it's no longer secret and your schema is not your secret sauce. The magic you provide is in the data, what the algorithms do, and the interaction between the resources. Each piece of information about your platform should be viewed critically to determine whether or not it should be shared with your developer customers. Sharing your long-term goals and strategy will also endear your developers to you. If they feel like they understand where the train is going, they're much more likely to get on board and come on the journey with you. Of course, it is sometimes necessary to keep information private to your company, but when that happens, say that too. Treat your customers as valued partners rather than interlopers and they will reward you with excellent integrations and relations. Extend Where Needed Now that I've encouraged you to stick with best practices when designing your API, it may surprise you to hear that sometimes you don't want to stick with a purely RESTful model. REST is an excellent way of describing most successful web APIs. However, in certain cases, you will need to move away from the strict REST philosophy in order to best serve the needs of your users. Your users need an API that will meet their goals easily and efficiently, so follow the industry best practices but remember, the number one priority is usability, so don't move away from established best practices unless you have a compelling usability-related reason why it's necessary. Frequently, all that's needed is to extend the notion of resources to allow clients to better express what they want to know about a resource. Expand and include related resources. I touched briefly on the idea of hypermedia APIs earlier and one of the things this technology can do is enable clients to express which related resources should be included in the response. The first company I worked for who used hypermedia used it in this way. Netflix provided resources for the movies and included in the representation links to the resources for the cast, directors, genres, and other related movies. For many API clients, such as video and mobile devices, the developer users wanted to be able to expand the related information inline and Netflix provided this functionality with query parameters to expand those links. Of course, as most people are aware, the open API was shuttered and they are using the technology strictly for partners, most notably for devices. Since the devices providing Netflix integration have a good level of bandwidth to support streaming, restricting of the sizes of resources isn't as important as providing a quick and rich developer experience. For this reason, allowing the API clients to request a rich, well-described set of information allows the devices to give you a fast and responsive experience. Another option is to create a query language. LinkedIn wanted to provide similar functionality for developers, but their information graph was much more complex. Each user was associated with many other resources and other users and expanding everything completely would have made for very large transactions. Instead, they created a more complex query language to enable clients to request a resource with specific portions of related information. So you could ask for a user, all of their contacts, and which city those contacts had gone to school in, without retrieving all of the other related information. Allowing people to express precisely the information they're looking for is one way to encourage creativity and innovation in the developers creating client applications. You may not know all the ways people will want to use your data, but if you have a rich interconnected system of data, creating this kind of query language can provide the flexibility and power that you need. When Etsy went API first, they went with a fairly strict resource model, but they wanted to meet the needs of their mobile and third party developers. In order to support this, they created a bespoke system to batch calls on the server end and return the representation to clients when requested. Making complete requests is another option. When I first started working with APIs, I used the Freebase API, which was an extremely complex interconnected graph of data. They had an API which was not at all RESTful but which I loved. You expressed exactly what you wanted to retrieve and got back exactly the information you had requested in the format described. You could, for instance, ask what movies featured an actor who was a Scientologist under six feet tall, married to another Scientologist and where and when their first child was born, without any extraneous information about any of the intermediate nodes. Freebase has been deprecated at this point, but there is a new technology which works pretty much the same way. GraphQL is a new query language which allows developers to express exactly what they want from the system, with no values included where the requested information should go. The response contains the entire response. This is a good option for complex graphs of information with considerable interlinking, where people may want to express or request for information in a variety of different structures. The system really encourages innovation for these systems and it's worth exploring if you're working to support complex or intersecting queries. I mean, who was that guy who played the Scarecrow in The Dark Knight and what other movies has he been in? This kind of question maps quite closely to how people process information naturally. Focus on Use Cases The final guiding principle I want to cover is use cases. If you take nothing else away from this module, I hope that you take away the value and importance of use cases in your design process. Without use cases to define the actions which should be easy in your API, it is far too easy to create a platform which is technically sound but difficult to use. For instance, if you have a social application and you want users to be able to write to their activity stream, you should define the steps developers would be to follow and make sure that work flow follows smoothly for clients using the API. A use case is a set of steps describing the experience that an end user wants, a story-based work flow, if you will. Communicating your use cases to customers is an easy way to demonstrate for them how important the platform is to your company and where it fits into the company strategy. Knowing what use cases you're supporting also helps your users understand more about the road map and goals of your platform as a whole. They can see what you're trying to do, understand where you want them to fit, and have confidence that they won't get a nasty surprise when the platform changes away from their targeted use cases. It helps them to avoid creating applications which aren't easy to implement and reduces your support burden by making it clear what kinds of interactions are supported and likely to be improved. Note that you don't necessarily want to stifle creativity among your customers. If they want to strike out on their own to create new and interesting uses for your API, that's fine, as long as they understand that their uses and functionality aren't your top priority for support. Yes, sometimes they'll come up with use cases that you don't want to support in the long run, but again, being clear about this with your developers, treating them like adult partners, is much better than trying to move around and shut down the functionality. Have your use cases as a communication platform and encourage developers to share their uses cases with you so that you can help them to implement functionality in the most efficient and effective way. Determining Business Value Now that you understand a few guiding principles for the development of a great API, let's talk about the process for designing and implementing that API. The next few sections will cover business value, metrics, and use cases, all of which will drive the design of the system you're creating. First, let's consider company value. This item is frequently skipped when building a new platform. It seems obvious that one should have an API but why are you creating it? What are you hoping to achieve? And most importantly, how is the API tied to the overall success and goals for the company? Without a strong guiding vision, the API is set up for failure and not likely to thrive. To get a better idea of why this is important, imagine that you're trapped in the elevator with the CEO and you only have a few seconds. The CEO turns to you and asks this terrifying question, so, why do we have an API anyhow? The answer, which brings to mind maybe, because we should have one. But, because APIs, is not very convincing for someone who is evaluating the need for a product which may not be producing revenue directly, but which is consuming valuable resources. If you can't tell your CEO why the API is important to the goals and vision for the company, you're risking an outcome where the API is shuttered, those resources are reassigned, and you no longer have a platform at all. Let's try to avoid that, shall we? Other than creating an API for API's sake, what kind of business values and goals can you target for the API? It may seem daunting to figure out why you're making the API, but consider it just like any other product. You don't create something for your users without knowing what problems you're trying to solve or how you're trying to improve their experience. Here are a few business goals you might strive for, all of which are strong contenders. It doesn't really matter what you pick, as long as you can give a meaningful and confident answer to the question, why do we have an API? Let's slide into a few different business goals and see what might work for you. Monetization is the most tempting business goal. You'll create the API and money will magically fall from the sky. At Netflix, the open API was created with a notion of letting a thousand flowers bloom, with the idea that creating an API would spawn countless applications, all inspiring new users to subscribe to the company's platform. They most assuredly did not want people to make those annoying pop-ups, trying to get you to subscribe, but because the API wasn't carefully designed and targeted to specific use cases, developers jumped on the ability to make easy money with widgets and pop-ups and the open API ecosystem never took off. If your company is based entirely on the success of your API, if you're a company like Twilio or Sun Grid and your business model is based on providing APIs to enable users to integrate with difficult technologies, monetization is a fine goal. But if your API is an adjunct to your main product and it's simply making your product line stronger, monetization usually isn't a great goal to pursue. If you have a social application, one of the best business goals you're going to have is driving usage. Encouraging people to interact with the system more frequently, giving them windows into your content from other sites and applications, generally enabling them to stay connected is valuable. It increases the value for those users and also improves the flow of social information provided by your application for all your users. Think of Twitter and Facebook as platforms and understand how valuable it is for them to allow people to like pages on other sites or tweet content they discover elsewhere. Even the social integration provided by shared log-ins increases the user's perception of the platform as an integral part of their online experience and improves the loyalty of the users of their platforms. So, let's face it, it's a lot cheaper for you to provide content via an API than it is to provide a full-fledged web application interface. Serving up content including all of the rendering, styling, and actions needed for the entirety of the site is expensive. One of the things that companies fear is allowing other developers to create experiences which compete with the main product, but truthfully, as long as customers are still seeing the value in the core of your business, it doesn't matter how they're getting to it. Feel free to enable other developers to use your API and give users a different interface into your system. It's less expensive for you and it can extend your reach to new users who aren't well-served by your default product. So here, a good goal is to move more of your traffic from the website to the API, to increase traffic on the API faster than the traffic on the product itself. And finally, another great choice is partner stickiness. If you find the pain points for your partners and customers and enable them to integrate more closely with your system to work around those, they have invested valuable resources in that integration. As long as your product line, including the API, provides value for your partners, they will be unlikely to want to switch to a competitor where they'll have to redo the work again. This is my favorite business goal, as it's incredibly valuable regardless of your industry. There are very few CEOs who won't be inspired by the notion of encouraging partners to stay around, providing consistent revenue and direction. Measuring Success Now that you've decided what your business goals are, you can move on to the next critical part of the process. This one's generally skipped as well, or at least glossed over. How are you going to measure the success of your API? You now know what you're trying to accomplish with your platform, so figure out reasonable ways to measure the success. This is going to help you determine the right use cases for designing your API and will also help you track how well your API is meeting your overall goals. I've seen many companies use poor metrics for their API and these are generally a symptom of a lack of overall vision for their API. For instance, frequently an API will be measured in terms of the number of developers who have obtained keys for the system. Well, this a reasonable measurement of the onboarding process for your API, it means nothing in terms of how usable and successful your API is. Similarly, counting the number of developers who have made successful calls to your API is also a measure of your onboarding process. The number of calls per month simply shows how many people are making calls, without determining whether those calls are meeting the use cases that you want to support. Think about what you want to accomplish with your API and tie your metrics to that. Overall metrics can still be valuable if you think about what you want your company to achieve overall with your API. But don't count how many calls are being made to the system overall. This can be skewed by a few applications which aren't using the system in a productive way. Instead, how many applications are accessing the API regularly, whether that's a thousand calls a month per customer or something quite different. Consider how your customers are continuing to use your APIs. How many customers are continuing to access the platform after three months, six months, a year, or more? Also, think about your use cases. What does your ideal client application look like and how can you measure your progress towards that goal? Other than general metrics, you can also measure how well the API is moving toward the business goals you've identified. If you've decided to work towards monetization, this is relatively easy to measure. How is the revenue of the API moving toward the targets identified for the company and platform? Similarly, if you're targeting usage, consider how frequently customers are engaging with the platform via the API versus using the main site. The more places people can touch your system, the more often they should be checking the feed and adding new content. Measure the engagement of your customers across all entry points to make sure that you're providing more breadth and opportunities for people to interact with your system. If you're aiming to move traffic from the main product to the API, consider how much of your traffic is going through the API versus the main website. As you get more applications and your applications become more successful, the growth of your API should exceed the general growth of your application. Check out the trend lines and use those to demonstrate engagement with the platform. These may not be the metrics you want to track, but there are certainly things that will be meaningful for your platform. How can you best prove success for your API? Create metrics that tell the story and use them to help guide your design and development. Creating Use Cases Finally, once you've figured out what you want your API to accomplish and how to measure success, you can figure out what use cases to support. Use cases are vital throughout the process of creating an API. Once you've defined the business value you wish to address with the API and how you're going to measure it, the resulting use cases will drive the rest of the process. During the process of defining your API using a modelling language, make sure that you can see how each piece works together to support each required use case. In the outer world, use cases are just like user stories. As an x, I want to y, so that I can z. In other words, a use case generally lists the steps a user would have to follow to create a desired outcome. Let's take a look at a couple of use cases to illustrate the point. Figure out what your main product would look like as a use case. Break down the functionality into subfeatures and design it as stories and substories. This is similar to an actual process and in fact you may well have done this exercise in the past during the product development of your main product. Take that information and look at it critically, as if you were designing the API just to best meet the functionality you want to provide, instead of simply creating the lowest common denominator interface, which is generally exposing your database interactions to the main product. Turn the use cases for the product upside down to figure out what an ideal API might support and use that as an example. Once you've figured out how to describe the main product, it should be relatively easy to figure out what a minimum viable product would look like. What are the core pieces of functionality for your product and how could you best provide those in a platform? This should help you to figure out how to develop the platform in a meaningful way by delivering specific functionality via the API in waves, allowing developers to create interfaces into the system in a meaningful way. This is superior to developing everything in parallel, potentially creating unrelated APIs or platform releases which don't support particular use cases. From here, your mobile application is an important use case. For mobile, you need to make sure that you understand exactly what functionality is needed and make those architecture choices I mentioned earlier to decide how to best meet the needs of a mobile client. One call per screen is critically important, so you need to determine exactly what makes sense to show on a mobile screen. Really take the time to think through the flow of the application so that you can provide meaningful endpoints and support the needs of a mobile developer. Remember that supporting a mobile use case will help you to provide a great interface for other applications as well, so it's often a good place to spend your energy. So I've now covered several ideas you might want to consider when creating APIs. Keep the general principles in mind and take the time to walk through the process I've outlined. Understand your business value and goals. Create metrics to guide your design and development. Develop use cases to help you understand and define exactly how you want people to use your platform and what you want to enable. Following these steps will help you through the next step, designing and developing your API and make sure that you get the system right the first time. Designing and Developing the API Concepts Now that we've covered the process for defining the API, it's time to move on to something with a little more meat, designing the API and developing it based on the business value, metrics, and especially the use cases that you've created. In this module, I'm going to talk about the reasons that schema modeling is valuable. Why take the time to create an artifact describing the API when you already understand the why, how, and what of the platform? Next, I'll walk through the process of designing the API using RAML, a schema modeling framework. While there are several modeling languages out there, the schema editing tools for RAML make it easy to get started, so we'll focus on that for this course. Finally, I'll talk about how you can use this model to create a roadmap for development of the platform. Following the schema model during the development cycle can help you to create releases which are both meaningful for your customers, and satisfying for your development teams. Why Create a Schema Model? So first, why create a definition document? What's the point of creating an artifact to describe the API when writing the code is a relatively simple process? What has happened to make this necessary? Looking back at the SOAP APIs, there was an explicit contract. The server laid out exactly what actions could be taken on the platform, the client implemented functions based around these actions, and there was no wiggle room. The contract meant that the API was tightly coupled to the client, and as long as the contract didn't change, the API was guaranteed to work the same. Adding new fields to a resource required a new revision of the contract and clients frequently needed to change the code to handle the newly changed resources even if they weren't using the new functionality. This was a very closed system which worked well for systems that were closely paired, such as a back end revenue system and the reporting database. Unfortunately, this same set of constraints meant that there was a reasonably large amount of overhead when a change needed to be made. Clients generally tied themselves to a specific version of the API and were wary of using newer versions as the interface to the objects could change, requiring a new model on the client side. On the producer side, changing or creating resources had a great deal of overhead in that they needed to consider how to change the contract, and what effects it would have on their clients. On the consumer side, the clients had to work to implement new functionality throughout their system whenever they pulled a new revision of the contract, even if they only wanted new functionality for a specific set of actions. So, we moved to a new model, REST. No contracts, yay! Now we could add new resources or add to existing ones without having to update a contract for the whole API. Resources were exposed rather than actions, so the interfaces didn't change between versions of the API, and clients could choose to implement the new functionality or ignore it as the additional fields wouldn't interfere with existing code. Innovation bloomed, clients were happy. Developers created consistent, beautiful implementations, making sure that everything made sense across an entire platform. No, wait, that last part didn't happen. We ended up in a world where the interface to part of the platform could be completely different from another parts of the API. Endpoints didn't have any kind of inconsistency imposed upon them by a contract. It was so easy to add new endpoints without going through a release process that developers didn't have any motivation to work with other parts of the team to make sure that the platform stayed consistent. Users ended up in a confusing world where they needed to implement code differently to access the exact same information and confusion abounded. Clearly, the no contract model had advantages, but it also had disadvantages that needed to be addressed. What Is a Schema Model? Enter schema modeling. There have always been people trying to find ways to describe REST APIs, but over the last several years, that has become much more popular as a way to enforce consistency and best practices on platforms. Creating a schema model makes it possible to review, document, and validate the design of an API before getting started on the code. But, what is a schema model? A schema model defines your API in a similar way to a SOAP contract. Each endpoint is described to show how the interaction works. For all endpoints, the different methods supported are detailed as well. Requests and responses are fully shown in order to allow readers to completely understand the interaction, and status codes are called out as well. Creating a schema model at its core means you are taking the time up front to make sure that your API follows the guidelines you've set out for your platform. You can define consistent requests and responses and impose requirements for error codes. This means that users of your API are going to be able to move between the endpoints smoothly without having to do extra work in order to integrate with different pieces of functionality. As a related item, a schema model allows you to check to make sure that the same resources are represented consistently across the platform. A user in the blogging model should be the same as a user in the account model. The identifiers match, the interface is the same, and the developer can add new pieces of information about each resource as appropriate to their needs. In fact, this is a great place to consider hypermedia or even adding expansion within the items to allow people to pull in additional data about the resource. If the back end resources are accessed the same way, it's easy to let people see where other information about the resource is available to expand or extend the data structure. Also, the process of creating a schema model allows you to take the time to map your use cases to the API to make sure that you're really meeting the goals laid out in your use cases. You can look at the model and see if those things you've identified as important are as easy as they should be. If someone has to make 17 calls to pull the information from a specific API, perhaps the definition needs to be rethought. Doing this exercise up front can save a lot of refactoring later, and keep your development velocity high. Nobody wants to redo work because it wasn't planned well at the beginning. In addition, a schema model provides you with items which can help you create a well-supported and usable API. First, the artifact itself, the schema model is something you can use to drive conversations with your customers, whether internal or external. Talking with the product managers and other groups at your company can help refine the requirements and guide you to additions or changes which might not have been obvious up front. Many times requirements make assumptions which aren't shared, and having a document which is clear and understandable, makes it possible to identify those issues up front. If you have customers who are targeted for the API functionality, a schema model allows you to have detailed conversations with them about exactly how the API is going to work before you get started creating the system. Remember that with an API, people tend to stick with the code they've already written, so you want to make sure that the API is as close to ideal as possible when it is first released. The best way to do that is to have a mechanism for communication before the coding begins. Each of the schema modeling frameworks, including RAML, the one we'll review here, provide some amount of interactive documentation for free. I'll talk more about the specifics of documentation in the module on empowering your developers, but suffice to say that nobody likes to write documentation. So creating a schema model as part of the definition process means that you'll get some of the most fundamental reference documentation out of the way in the process. This is one reason many companies choose to use schema models, and I'm perfectly fine with that. Anything that encourages people to do this planning up front makes for a better developer experience, so I'm all for whatever helps make that happen. In addition to interactive documentation, each of the frameworks provides open source tools to run mock servers, so you can test calls to the system and even create proof of concept sample clients. For some customers or internal interested parties, the schema model itself will still be too abstract and creating that sample client can really communicate what you're trying to do. As well, this exercise makes it really easy to test out those use cases and make sure they're working exactly as you hope. Tease out the hiccups in the system before taking the time to create it. In short, creating a schema model is like doing the first step of coding up front. If you want to make sure that your API is consistent and usable, writing down exactly what it's going to do upfront will provide you with a framework for creating an API right the first time. Schema Modeling Overview Now, let's move on to actually modeling the schema itself. Again, for this example, I'll be using RAML, the RESTful API Markup Language originally designed and supported by MuleSoft. This demo will go through the following concepts. First, I'll show you how to get started with the API designer. There's a little overhead in getting started the first time, but it's a free system and your models will be persistent over time, so it's a worthwhile exercise. Next, we'll create an API within the API designer. I'll use the example from the Docker Container or GitHub repository we set up in the module on web services. There are schema models in the schema directory of that repository so you can work with that one after we go through the general layout and setup. When the API is first created, it will come with some metadata. I'll cover the various pieces, so you can understand how they interact with the overall structure. We'll pull in the example schema after this from the Docker Container, so you can see how it all fits together. Next comes the meaty part of the schema model, the endpoints themselves. I'll walk through the definition for the top-level resource, the quotes list. The endpoints are defined hierarchically, and I'll show you how additional sub-resources can be entered. Each method for an endpoint is defined separately, and you'll see how that's structured in the data model. I'll show you how parameters are defined. The status codes covered in the web services module drive the response codes used in the document. And each request and response may have a body associated with it and in the definition, you can define what that would look like. I highly recommend doing this any place a body is appropriate. We'll look at a basic response body for the quote server, as well as the body needed to add a new resource to the system. As we build up the model, the documentation in the right hand console will be auto-generated. We'll take a look at what this gives you in terms of free documentation, so you understand the value of this functionality. Modeling Your Schema Using RAML Let's get started working with the API designer. Start at RAML.org. Again, RAML stands for RESTful API Markup Language, so the URL is RAML.org. Select Projects in the navigation bar. Select API Designer. Try it out from the list. From here, you'll need to create a new sign in for the system in order to create an API. It's a simple enough form. As with many signups, you don't have to put in a valid email address if you don't want to get marketing emails from the company. Once you've signed up, you'll be logged in automatically, and you'll be ready to get started. On this page, click API Manager. Click Add new API. Fill in the form here, and when you're done, you'll have an API to work with. Under API Definition, select Define API in API Designer. As you can see here, some metadata has been created based on the form entries we used. The RAML version is 0.8. The most recent version of RAML is 1.0, but 0.8 is fine for our purposes here. The title, version, and base URI have been pulled from the form and we're ready to get started. To quickly populate the form, I'll paste the contents of the polyglot.raml file from the schema's directory of the Docker Container. Now we have the structure of a fully defined API. Let's step through and see what each piece does. First, I'll minimize the methods, so that you can see the overall structure. As you can see, the quotes endpoint defines the top of the endpoint structure. The random and quote ID endpoints are nested underneath this endpoint, so random is actually /quotes/random. Adding this to the base URI, you would end up with http://fortunecookieserver.com/api/v1/quotes/random. You can see here that the methods match what I discussed in the web services chapter. You can get the top-level list to see a list of the quotes or post to create a new quote. You can get a random quote, and for an individual quote, you can get it, put to update it, or delete it. Now let's dive in deeper to see how each endpoint and method is structured. Under quotes, I'll expand the get method. First up, there's a description of the endpoint. This is used for documentation purposes, and it's helpful to have a descriptive string here for reference. Next, you can see how query parameters are defined. Again, there's a description and a few fields to define the behavior of the query parameter. These are get parameters, which show up on the URL with the standard question mark delimited by ampersands, and defined with equal signs. Query parameters is an optional field, not needed for a complete definition, but if your endpoint does accept parameters, put them here. Next come the responses. These are organized by status code. The first one is generally going to be the successful response. In the case of get, this will be a 200 successful code. This response comes with a body of type application JSON, and you can see here what the structure of that response will be. Note that because we're getting a list of quotes, the JSON represents an array of items even though there is only one item included in the example. Next comes post to add a new item to the list. In this case, the request has a body associated with it, so it shows up right after the description. Again, it's application JSON, and we can see what the expected structure will be for that post. Under responses, the 201 created shows what information will come back. The index for the new item and the 500 response demonstrates exactly what will be returned in case of a server error. It's best to lay out all of the possible status codes in the documentation, so readers know what the potential outcomes are when calling endpoints. Take some time to explore the remaining endpoint method combinations to see what else is possible here, and let's take a look at the interactive documentation on the right. For each endpoint, there is a tab representing the methods available. Let's take a look at the documentation here for get for the quotes resource. Under the request, you can see the description and information about the query parameters from the schema model. For a response, the status code is called out. In this case, there's just one for a 200 response, with the content type and a nicely formatted printout of the example JSON. Take the time to look at the other endpoints and tabs to see how the interactive documentation console works. As you can imagine, this is much higher quality documentation than most and you get it for free just by doing the work of modeling the schema up front. Design-driven Development In this final section, I'll talk about using the work you've done to guide your development team to create smaller, more meaningful software releases. First, let's talk about the evolution of software process methodologies. Originally, there was waterfall design. This was largely a serial process, where an entire feature set was created and designed up front, and the development team went heads down for months at a time, emerging to release the next big thing into the world. This increased overall visibility into the overarching goals, but it wasn't great at keeping teams on track with changing or evolving requirements. Customers wanting only part of the changes needed to wait until the entire new feature set rolled out in order to get what they were waiting for. The overall process was designed like a hardware process, where the individual components couldn't be changed during the process of creating the end product. Additionally, the code was written to the specification and tests were written after the code to make sure that it worked correctly. Agile development incorporates many concepts and I'm not going to go through all of them here, but one of the main new ideas introduced in the Agile world was test driven development. Instead of writing tests after the code is written to make sure it does what it says it does, tests are written up front based on the requirements. These tests will obviously fail to pass until the code is written, but because the tests are based on the requirements and not on the code itself, the resulting functionality is much more likely to meet the original goals. So, test driven development was a big step forward in terms of user-oriented development. More recently, teams have started working on behavior driven development, which incorporates integration testing. Not only do individual functions need to behave correctly independently of each other, they need to function correctly within the overall product. Again, these tests are designed and written before the code pieces are written, and this helps make sure the team is aligned and moving toward the vision for the product together. As an abject of this, design driven development takes the use cases developed earlier in the course and applies those to behavior driven development. Those integration tests are tied directly to the use cases which need to be easy and efficient, rather than simply making sure that the system works together correctly, the usability of the system, it's interfaced to the customer, holds the final determination of completeness for the release. Creating a schema model is the first step to this and integrating your use cases makes a complete model for successful API development. What are the advantages of design driven development? First, and most importantly, it keeps your overall development roadmap on track with your use cases and schema model. When individual feature requests creep in, which aren't associated with your targeted use cases, they need to go back through the original process to be assessed. This keeps your team on track and focused, and provides a great way to communicate to your customers and other teams what your team is working on in a way that's meaningful. When you focus your development roadmap on the design you've created, the product releases are meaningful to your customers. "Oh great, now I can wash my dishes," is much better than saying, "We've updated these three resources." Communication with customers around workflows makes for a happier experience all around. Developing in this way helps keep your developers on track and on target. The velocity is higher, because you're not allowing unrelated changes to creep in, and deploying meaningful releases is much more satisfying than iterating on items which aren't giving customers useful new functionality. All of this adds up to a reduction in the need for refactoring later. When you focus on use cases and know exactly what you want to enable, the development process runs much more smoothly than if you simply identify specific functions and hope they work together seamlessly. Your schema model acts as a template for development and your upfront design work will save you countless hours and frustration during the development cycle. So, to review, this module focused on the process of designing and developing your API. First, I talked about why schema models were important and what they were. The second section covered the creation of a schema model. And finally, I talked through how you could use your use cases and schema model to guide your development team to creating a great API effectively and efficiently. Empowering Developers Empowering Developers: Overview This next section is on empowering developers. Now that you have a process for planning, designing, and developing an API, it might seem like your work is done. But you still have some work to do. The cornerstone of a great API is a fantastic developer experience. Creating a platform that is engaging, inspiring, and usable, does you no good at all, unless your users can find their way to the amazing product you've built for them. Help them learn about the platform and what it can do for them, by exploring a portal of information providing them with a window into the system. Along with communication, which was discussed in the module on defining your API, the pillars of a great developer experience are complete and compelling documentation. The documentation you create will need to have the basic reference information for each of the endpoints, but you will additionally need to create different ways to inspire and engage your developers with the platform. Guides and tutorials based on the use cases you identified are important, as are blog posts and other narrative explanations about how the platform works together as a whole. Building blocks. Marketing to developers isn't like marketing to regular people. Pictures, words, and slick handouts won't inspire them. But code samples and reference applications will. I'll talk about different approaches to provide fun and quick ways for developers to interact with your system and become engaged. And support. How you will support your customers is going to depend on your company's needs and direction, but you need to determine your support model explicitly and cover all types of customer questions. I'll go over some of the options you have available for supporting the platform user. Documentation: Reference Documentation The first and most obvious piece of empowering your developers is your documentation. This is, in many cases, your first impression for the customers and it can set the tone for how the developers will feel about the platform and what it can do for them. Your documentation will fall into three general categories and you need to address each one to make sure you've got all the right pieces to help a developer learn about your platform. The types of documentation are as follows: Reference documentation. What does it do? This is where you give information about what each piece of the platform does and how it behaves. For many companies this is all the documentation they provide. While it's necessary, it's definitely not sufficient. Tutorials. How do I get started? Beyond the more specific guides, your developers will likely need to know how to get started with the system. This is frequently skipped as it's hard to imagine people who aren't already familiar with your system, but in the real world, this is one of the biggest drivers of customer satisfaction with a platform. And Guides. What can I do with your platform? These are workflows to help your customers understand what they things they can do with the API. Many times there are multiple steps to achieve a particular goal, and by laying out these steps explicitly you make it possible for developers to figure out how to accomplish goals with your platform. Reference Ddcumentation. Diving down, little bit deeper into the reference documentation. This covers items such as endpoint documentation, system guides, and complete requests and responses. Endpoint documentation. As discussed briefly in the section on designing and developing your API, creating a schema model will help you to create some amazing documentation about endpoints. Great endpoint documentation covers each endpoint in the system, what each method does, and what requests and responses will look like for that specific endpoint. Here is an example of endpoint documentation, such as what you might get from a schema model. No matter what technology you use to create your endpoint documentation, even if you write it manually yourself, each entry must have information such as what's shown here. First, what's the method being documented? Each endpoint and method needs to be broken out clearly and completely. Even if a put and post are very similar, for instance, you want to lay out exactly what's needed for each because your users will drill down to exactly the function they want to use. Next, what's the end point? Specify explicitly and completely. Don't have a page about the API quotes method and then a subsection for the ID endpoint. Each time, lay out the complete endpoint clearly. Somewhere in the documentation for the method and endpoint you should specify what the content-type header should be for the transaction, whether requests or responses. Users need to know if the post should be sent with a body of application JSON or WWW URL form encoded. Information about needed parameters and optional parameters needs to be sent as well. The documentation should make it clear which is which, so a user knows exactly what a successful call needs to work. There should also be an example body for both requests and responses. For a request, the example should show what the expected body will look like. If there are multiple different combinations of parameters which change the expected request body, there should be examples of each in this section. For any query which returns a response, the example response body needs to be shown as well. Many API developers feel that these example bodies aren't important, as the developers can always call the endpoint to find out how it works. And there's overhead in keeping the documentation in sync with the actual API, including responses in the documentation isn't a good idea. However, developers who are looking to implement an integration with your platform will be quite unhappy if they're required to make calls to the API simply to find out exactly how the endpoint works. So this should demonstrate one of the reasons it's so valuable to do schema modeling for your API. Even if you don't use the schema model for anything else, the documentation which can be provided for your APIs is really a powerful tool for your developers. Along with the static documentation shown here, each of the schema modeling language supports open source libraries to provide a mock server or console, so that developers can input parameters and see how those responses would look when sent to the API. You'll want to provide regular references to your system guides within endpoint documentation so that someone who searches on a particular piece of functionality can figure out how to work with the platform as a whole. Endpoint documentation is the foundation of your documentation and you need to make it solid. Let's look at a couple of other pieces of your reference documentation to complete this section of your overall documentation strategy. Documentation: System Guides The second type of reference documentation is system guides. Developers frequently have questions about the overall platform, architecture, and design. Understanding how the system works and how the pieces work together can provide a great, high-level overview of the API. System guides include information on the following: Header information for working with this system. What headers does the system expect in return? Which ones are optional versus required? How is content-type handled? Does the server return different response times based on what's requested by the client? Your system likely has some kind of authentication and authorization functionality and while you don't want to include information about this in the documentation for each endpoint, you do want to refer back to it so that if someone jumps into one of these pages, they can understand how to make these calls. What error codes are returned by the system as a whole and what do they mean? And, how should a developer catch and handle them? If you implement rate limiting, for instance, your documentation should clearly include the steps to follow if developers hit those limits. Should they back off? How long should they wait? What should they do to request more calls? The final piece of reference documentation is the request-response model. Your data model should be consistent across all endpoints and predictable for developers working with the system. Laying out your data model here, allows people to predict how the different pieces of the platform will behave and interact. These three pieces of information should be interlinked liberally, so that developers interested in understanding all of the pieces of functionality and how they work together can build a mental map. Don't just provide them with a sheet of papers without any index or narration, help them to explore without having to ask for help from you. Provide good context. Documentation: Tutorials and Guides The second major section of documentation is tutorials. These help a developer during the all-important ramp up on your system. These guides need to make it easy for a new customer to get to a successful first call to the system. Think of it this way, a new visitor is anxious to determine whether your system is going to work for them. They will probably allocate about 10 to 15 minutes to make a cursory examination of your platform. If you can help them make a successful call during that time, you're likely to buy yourself another 20 to 30 minutes or more for them to look a little deeper at the different options your API provides. Your tutorials should always include sample code, a set of how-to steps, and troubleshooting information. Some of the things you'll want to consider when making tutorials are the following: Who are my customers? What operating system and tools are they used to using? How much experience do they have with APIs? And what do they want to do with the system? Your developers are going to be coming from a variety of development environments. Some of them will be Windows developers used to programming in an IDE. Many of them will use Macintosh systems and be comfortable in a Unix command line environment. You'll likely have a few Linux users as well who also work well on the command line. As well, you need to consider the programming languages your developers will be familiar with. Many of them will be Java and C# developers, so even if you don't have that knowledge on your team, you need to be aware that they may not be familiar with other programming languages. There's another group of people very comfortable with one or another interpreted language such as Python or Ruby. Most developers have at least a passing knowledge of JavaScript because web interaction has become so common. When you're deciding what language your language is to support, try to provide the widest range you can, remembering that you probably won't get all the developers, so you need to give some information about the language as well, to help them work with the tutorial code. Don't make assumptions that your customers are like your development team. API consumers work on different technologies than the producers do, and your advocates and evangelists may not be used to working on the enterprise technology stack of your customers. Don't despair, just remember that you need to understand where your customers are coming from when providing tutorial information. There are some different options for helping customers set up an environment to get started. If you have a large percentage of Windows users, setting up an interpreted language such as Python or JavaScript, may prove to be a difficult burden for them to overcome. You want them to get that first call made within five to 10 minutes, and if they're spending 25 minutes downloading and installing an operating system or platform they may get discouraged and give up. There are a couple of different technologies you can use to help users get up and running if they're not already running one of the languages you feature in your tutorials. I've used Docker and cloud platforms, such as Codeanywhere for this purpose. Docker is a good option for allowing people to get a working environment all set up with the needed environment. Docker provides a native client, just recently released, which makes it possible to run a very low maintenance, lightweight, virtual machine on Windows, Macintosh, or Linux. One major advantage to using Docker, is that you can run any needed setup and pull in required libraries during the container creation, so the users can get right to the steps they need to follow to make those calls to your system. One disadvantage to Docker is that unless you use a slightly more complex set up, editing files within the container requires understanding of a command-line-based editor such as Nano or Vim. Systems like Codeanywhere are nice tools for users who want to explore a system in the cloud. These system create an internet-reachable Linux environment. They provide a browser IDE, where users can edit the files in a GUI editor, and users can input commands and see the output in a webpage provided by the system. These are a great way for people to explore a system without having to install anything on their own systems. One thing to keep in mind is that with either of these technologies, or anything that abstracts away the setup, users aren't interacting with the system in their own development environment and they're thus going to have to do some work to use the system in their own workflow. It's great for a proof of concept, but less awesome in terms of really getting them hooked in using the system on a regular basis. When you're working with software developers, who want to consume your API, you'll likely come across some who are well-versed in consuming APIs, along with many who have never worked with web services at all. Don't make assumptions about what they know or don't know. Make sure that you give enough information to provide context, so that when you ask a question about what the headers or context body was they understand what you're asking. One of the things that can happen with SDKs and other abstraction tools, is that users aren't certain exactly what's happening with the system. And you need to do extra work to support their use because they're not familiar with the technology on the back end. Similarly, if they don't have experience working with APIs, they're not likely to be familiar with authentication and authorization functionality. So it's important to make sure that your tutorials on getting started step through this piece of information as clearly as possible. If you're authentication is non-standard, or if there are libraries provided in multiple languages, make sure you include information about why your authentication works the way it does and point to the system guides on the authentication system needed for your system. What do you want your new users to do with your system? Are they looking to integrate it with existing applications? Create new applications? Are they interested in pulling reports or automating alerts? Consider the question, why do I care, when thinking about the types of actions you want to include in the getting started tutorial, and which languages you're going to include. You generally don't need to create full-fledged reference applications instead of code samples, but including a few tutorials with example code for very common use cases, or things you want to encourage your users to consider, allows the user to understand what you want them to do. Point to the strong functionality, which solves your customer's or partner's pain points, and help them get excited about the system while learning how to use it. The third major section of your documentation is guides. These are examples of workflows that your developer customers can follow to use your system. Frequently, APIs require that someone call one endpoint to get the information for a second endpoint, and so on, until the whole train of calls is up to an incomprehensible mess. Creating a guide for users will help them to understand how the chain works together and what they need to understand in order to interact with the system. Let me go over an example to show you how this kind of guide can be helpful. In this example, the developer is integrating with an API for retrieving a billing report from the system. First they need to call the reporting group API to get the account number. Next, they need to make a call to find out the property ID for that account. Next, using the property ID and account ID, they can get a list of product IDs associated with that combination. Then, using the three previous pieces of information they can get a list of measurements and statistics. And finally, using all these pieces, they can retrieve the billing report. Now, is this API designed with a great developer experience in mind? Not exactly. But you're sometimes going to come into a world where the APIs you need to support are more complex than they should be and guides provide you a way to communicate with your users about what they can get from the platform. Building Blocks As I mentioned, marketing to developers isn't like marketing to regular people. Developers don't want pictures, slides, and words, they want toys and tools they can work with and make stuff happen. In order to truly engage your users, you need to provide things that work quickly and effectively to interact with your platform. Some of the different types of building blocks you can provide are Authentication Libraries, Sample Code, Reference Applications, and Tools and Techniques. Let me dive down into each of these for a closer look. Whatever your authentication scheme is this is likely to be one of the stickiest pieces of working with the system. This set of utilities is critically important to the success of your platform. But what is an authentication library. An authentication library is not an SDK. It should take a standard HTTP object from the language in question, override the authentication, and provide simple interaction with endpoints without any fancy programming. Authentication libraries should be presented in as many languages as possible, even if there are no other code examples provided in those languages. You should encourage and support developers who want to provide new authentication libraries in their language by testing and verifying functionality. Authentication libraries must be vigorously tested and verified to work consistently. Sample code is the bread and butter of your building blocks. If you have a solid set of code examples people can work with, they're much more likely to get started working with your system. Your code sample is likely to be closely tied to your tutorials and guides. For any code sample, it should be well-documented. Make sure than any tutorial or guide closely matches the code in the sample. If you're going to cover multiple languages, try to keep the various examples as consistent as possible between them. This makes it easier to have consistent guides using the code, and helps people to move between the examples as they want to. Sample codes should be as clear as possible without a lot of abstraction or complicated logic. You're not trying to teach the developer how to program, you're just showing basic interaction and logic with the objects. The tutorials and guides I discussed in the documentation section need to have sample code associated with them in the languages you've decided to cover. The more examples the better. Remember that for this kind of sample, you're trying to help people get up and running quickly, so all a user should need to do is grab credentials and go. Downloading new programming languages or doing complicated set-up steps just get in the way of the experience and can make the task seem tedious. For tutorials, you'll want to support as many different languages as possible, with the exact same sample for each. When you do this it becomes possible to have a getting started tutorial that can work for many classes of developers and reach people where they are, rather than asking them to leap into a different framework to understand your system. For guides, it's less important that the code be written in multiple languages. It's more important that the logic flow is clear and easy to follow. For these types of code samples, I tend to use Python as it's the most readable languages for people who don't understand the language. It looks a lot like pseudocode and you want to make it easy for people to find and understand the example so they can import it into their own development environment. Don't get fancy. A getting started tutorial doesn't need to be exciting or innovative, you're just trying to help a developer understand how to use a system, and the more complexity you include in the code, the less able they'll be able to understand how the basic interaction works. Make sure that the guides you include show the best practices for interacting with your system. However you want people to access and work with the resources, make sure that's consistent throughout all of your tutorials and guides. Reference Applications and Tools To get beyond the code samples, which include tutorials and guides, and start really inspiring your developers, you need to think about adding some reference applications. These are especially useful for very complicated APIs, which provide flexibility and power at the expense of simplicity. What is it the people can really do with the API? How do the different pieces work together? Sometimes a web application is really the best way to answer these questions, so creating a few reference applications is a great idea. When creating reference applications, keep the following in mind: Choose a language that's going to be as comfortable as possible for developers, which can be installed and run easily and quickly. Node.js is generally the language I've used for this kind of application, as the server is easy to run. JavaScript is a language most developers have used and the libraries make it easy to integrate needed functionality into the system. Within a reference application, it's even more important to demonstrate the best practices you want people to follow when working with your platform. You'll be working with multiple endpoints and moving resources around. How do you want people to access these objects? Which keys should be used to refer to the different objects? And a reference application should be interesting. Choose functionality that you know your customers want. If your API is modeled after your main product, choose functionality that's very popular within the main product. The closer you can tie the API integration to something people want to do, the more engagement those reference applications will inspire. Along with the code samples you provide to help people integrate with your system, don't forget about other ways that developers can explore and interact with the system. There are various tools out there to work with APIs, to help understand the features and functionality of the platform. Some of the tools available for customers to use include mock servers. A mock server runs on top of a schema model and makes it possible to see what a request and response would look like for that platform. The interactions aren't persistent, they simply show what a call would look like if it were to happen. And in this kind of interface can make it much easier to understand for some developers, rather than other documentation. Consoles, taking it to the next level, consoles are generally web interfaces to make API calls to the back-end server. They abstract away the authentication layer and show what the requests and responses look like against the live server. Apogee provides a console that many different platforms use and all of the schema modeling languages provide some kind of console functionality. This is more real than a mock server interface and is a great way to show developers how to explore your API. Command line utilities. Lots of developers love cURL. I personally think it's a little hard to use and I prefer another tool set HTTPie. But the fact remains that many developers are most comfortable on the command line and you want to make it possible for them to interact with the system using command line utilities. cURL and HTTPie are two different command line interfaces you can demonstrate and showing people how to explore the API using the command line can encourage them to spend some time trying to understand what's possible with your platform. HTTP Sniffers. These tools make it possible to watch HTP traffic as it moves between this client and the server. They're a great way to understand the interactions. The Chrome browser developer tools allows you to watch the traffic generated by the browser. Postman is also available for in-browser interaction and for watching traffic outside of a browser you can use an HTTP sniffer application like HTTP Scoop, Fiddler, or Charles. Developer Support The final pillar of developer experience is developer support. You need to know what your support strategy is for your platform upfront, so that you can staff and respond appropriately, and so that you can set expectations appropriately with your customers, so they know when and how to get help. Without a shared understanding of how you'll be helping them, developers will get frustrated and demotivated and your platform will suffer from negative sentiment. As well, taking the time to listen to the concerns of your developers will help guide your future roadmap and create excellent on-point documentation for the various functions. Some companies have support staff around the clock for the main products of the company. This is an excellent resource to leverage for API support as well. Your API should be supported alongside all your products, and training your existing support staff about the API, so that the channel is the same is frequently the most efficient way to support your developers. It supports the message that your API is a first-class product your company cares about. And using these resources gives your developers access to a channel which is staffed regularly and has processes in place for answering issues and questions. This is a better solution than having your developer relations team answer questions from customers, as these folks are generally not trained in customer support, aren't scheduled to work support hours, and aren't available around the clock. If you can't support the platform through the existing support channels, or even if you can, you should provide some sort of community forum for your customers. This is an excellent tool your developers can use to ask questions and engage in conversations about the APIs. Your developer relations team can use the forum to engage with the developer community and answer questions. Frequently forums generate ideas that can help drive future functionality and features. If you use a customer forum, it's important to make sure that you watch it carefully and make sure that your customers have the correct expectation of how frequently questions will be answered and help will be given. When you have an open API where customers aren't paying for access to the API, you may need to fall back to this model in order to provide support in an appropriate way. Email is a terrible idea for customer support. Please don't use it. Email isn't well tracked. Messages can get lost in the shuffle. There's no shared knowledge base of questions and answers. And when someone leaves your company, the history of all the messages are lost to the ether. Helpdesk software such as Zendesk, on the other hand, is a nice solution for organizations who want to provide support for their users. There's a shared knowledge base of previous questions and answers, which can populate a facts section. Email interaction is supported for customers who don't want to interact on the website. Reminders are sent to the supporting teams so that they know when cases are pending a response. And template answers can be used to give answers to frequent questions. Whatever your support strategy, the frontline soldiers need to have access to back-end resources to answer questions. Again, since your API is a first-class product, this interaction should be expected and supported, not seen as a challenge or issue without any kind of organizational support. In short, simply realize that supporting an API is necessary to the long-term success and health of your developer ecosystem. Plan for this upfront, and make sure that you're ready for the inevitable questions and issues, so that you're on the case and not caught out without resources for questions and answers to interact with the system. So again, looking at empowering your developers, there are three pillars of customer support. Documentation should be well thought out and consistent with reference documentation, guides, and tutorials. Building blocks should be created with code samples, authentication libraries, and reference implementation. And finally, your support strategy needs to be well planned out and communicated to your customers. Course author Kirsten Hunter Kirsten Hunter is an unapologetic hacker and passionate advocate for the development community. Her technical interests range from graph databases to cloud services, and her experience supporting... Course info LevelBeginner Rating (76) My rating Duration2h 0m Released3 Nov 2016 Share course