INITIALIZATION Knowledgebase: ki-dev-large Base Query: can you give me a random fact from Web API Design Model: gemini-1.5-pro-preview-0409 Use Curl?: None ================================================== **Elapsed Time: 0.00 seconds** ================================================== ROUTING Query type: research ================================================== **Elapsed Time: 2.23 seconds** ================================================== RAG PARAMETERS Max Context To Include: 20 Lowest Score to Consider: 0.5 ================================================== **Elapsed Time: 0.14 seconds** ================================================== VECTOR SEARCH ALGORITHM TO USE Use MMR search?: False Use Similarity search?: True ================================================== **Elapsed Time: 0.10 seconds** ================================================== VECTOR SEARCH DONE ================================================== **Elapsed Time: 0.72 seconds** ================================================== FILENAMES AND KEYWORDS Keywords Found: ['design', 'API'] All file names: ['Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf', 'Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf'] File names to FILTER: ['Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf'] ================================================== **Elapsed Time: 1.08 seconds** ================================================== PRIMER Primer: You are Simon, a highly intelligent personal assistant in a system called KIOS. You are a chatbot that can read knowledgebases through the "CONTEXT" that is included in the user's chat message. Your role is to act as an expert at reading the information provided by the user and giving the most relevant information. In your responses to enterprise users, prioritize clarity, trustworthiness, and appropriate formality. Be honest by admitting when a topic falls outside your scope of knowledge, and suggest alternative avenues for obtaining information when necessary. Make effective use of chat history to avoid redundancy and enhance response relevance, continuously adapting to integrate all necessary details in your interactions. Focus on precision and accuracy of your answers information. ================================================== **Elapsed Time: 0.00 seconds** ================================================== FINAL QUERY Final Query: CONTEXT: ########## File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 1 Context: ```markdown # Web API Design ## Crafting Interfaces that Developers Love ### Author: Brian Mulloy --- ### Table of Contents 1. **Introduction** - Overview of Web APIs - Importance of Good Design 2. **Design Principles** - Consistency - Simplicity - Flexibility 3. **Best Practices** - Documentation - Versioning - Error Handling 4. **Tools and Frameworks** - Postman - Swagger - RAML 5. **Conclusion** - Summary of Key Points --- ### Links - [Postman](https://www.postman.com) - [Swagger](https://swagger.io) - [RAML](https://raml.org) --- ### Notes - Always aim for clarity and conciseness when designing APIs. - Engage with developers to understand their needs and challenges. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 2 Context: ```markdown # Table of Contents ## Web API Design - Crafting Interfaces that Developers Love 1. [Introduction](#introduction) ....................................................................... 3 2. [Nouns are good; verbs are bad](#nouns-are-good-verbs-are-bad) .......... 4 3. [Plural nouns and concrete names](#plural-nouns-and-concrete-names) ... 8 4. [Simplify associations - sweep complexity under the ‘?’](#simplify-associations) ........................... 9 5. [Handling errors](#handling-errors) ................................................................. 10 6. [Tips for versioning](#tips-for-versioning) ................................................... 13 7. [Pagination and partial response](#pagination-and-partial-response) .......... 16 8. [What about responses that don’t involve resources?](#what-about-responses) .......................... 19 9. [Supporting multiple formats](#supporting-multiple-formats) ........................ 20 10. [What about attribute names?](#what-about-attribute-names) ...................... 21 11. [Tips for search](#tips-for-search) ............................................................... 22 12. [Consolidate API requests in one subdomain](#consolidate-api-requests) ... 23 13. [Tips for handling exceptional behavior](#tips-for-handling-exceptional-behavior) .... 25 14. [Authentication](#authentication) ............................................................ 27 15. [Making requests on your API](#making-requests-on-your-api) .................. 28 16. [Chatty APIs](#chatty-apis) ............................................................. 30 17. [Complement with an SDK](#complement-with-an-sdk) ............................. 31 18. [The API Façade Pattern](#the-api-facade-pattern) .................................... 32 ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 3 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ## Introduction If you're reading this, chances are that you care about designing Web APIs that developers will love and that you're interested in applying proven design principles and best practices to your Web API. One of the sources for our design thinking is REST. Because REST is an architectural style and not a strict standard, it allows for a lot of flexibility. Because of that flexibility and freedom of structure, there is also a big appetite for design best practices. This e-book is a collection of design practices that we have developed in collaboration with some of the leading API teams around the world as they craft their API strategy through a design workshop that we provide at Apigee. We call our point of view in API design "pragmatic REST," because it places the success of the developer over and above any other design principle. The developer is the customer for the Web API. The success of an API design is measured by how quickly developers can get up to speed and start enjoying success using your API. We’d love your feedback—whether you agree, disagree, or have some additional practices and tips to add. The [API Craft Google Group](https://groups.google.com/g/api-craft) is a place where Web API design enthusiasts come together to share and debate design practices—we’d love to see you there. ## Are you a Pragmatist or a RESTafarian? Let’s start with our overall point of view on API design. We advocate pragmatic, not dogmatic REST. What do we mean by dogmatic? You might have seen discussion threads on true REST - some of them can get pretty strict and wonky. Mike Schinkel sums it up well - defining a RESTafarian as follows: > “A RESTafarian is a zealous proponent of the REST [software architectural style](https://en.wikipedia.org/wiki/Representational_state_transfer) as defined by Roy T. Fielding in Chapter 5 of his PhD dissertation at UC Irvine. You can find RESTafarians in the wild on the [REST-discuss mailing list](https://groups.google.com/g/rest-discuss). But be careful, RESTafarians can be extremely meticulous when discussing the finer points of REST ...” Our view: approach API design from the ‘outside-in’ perspective. This means we start by asking - what are we trying to achieve with an API? The API's job is to make the developer as successful as possible. The orientation for APIs is to think about design choices from the application developer's point of view. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 4 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love Why? Look at the value chain below – the application developer is the lynchpin of the entire API strategy. The primary design principle when crafting your API should be to maximize developer productivity and success. This is what we call pragmatic REST. ![Value Chain](url_to_value_chain_image) ## Pragmatic REST is a design problem You have to get the design right because design communicates how something will be used. The question becomes - what is the design with optimal benefit for the app developer? The developer point of view is the guiding principle for all the specific tips and best practices we’ve compiled. ## Nouns are good; verbs are bad The number one principle in pragmatic RESTful design is: keep simple things simple. ## Keep your base URL simple and intuitive The base URL is the most important design affordance of your API. A simple and intuitive base URL design makes using your API easy. Affordance is a design property that communicates how something should be used without requiring documentation. A door handle's design should communicate whether you pull or push. Here's an example of a conflict between design affordance and documentation - not an intuitive interface! ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 5 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ![Push doors](image_url) A key litmus test we use for Web API design is that there should be only **2 base URLs per resource**. Let's model an API around a simple object or resource, a dog, and create a Web API for it. The first URL is for a collection; the second is for a specific element in the collection: - `/dogs` - `/dogs/1234` Boiling it down to this level will also force the verbs out of your base URLs. ## Keep verbs out of your base URLs Many Web APIs start by using a method-driven approach to URL design. These method-based URLs sometimes contain verbs—sometimes at the beginning, sometimes at the end. For any resource that you model, like our dog, you can never consider one object in isolation. Rather, there are always related and interacting resources to account for—like owners, veterinarians, leashes, food, squirrels, and so on. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 11 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ## Facebook No matter what happens on a Facebook request, you get back the 200-status code - everything is OK. Many error messages also push down into the HTTP response. Here they also throw an #803 error but with no information about what #803 is or how to react to it. ## Twilio Twilio does a great job aligning errors with HTTP status codes. Like Facebook, they provide a more granular error message but with a link that takes you to the documentation. Community commenting and discussion on the documentation helps to build a body of information and adds context for developers experiencing these errors. ## SimpleGeo SimpleGeo provides error codes but with no additional value in the payload. ## A couple of best practices ### Use HTTP status codes Use HTTP status codes and try to map them cleanly to relevant standard-based codes. There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them. Therefore, most API providers use a small subset. For example, the Google GData API uses only 10 status codes; Netflix uses 9, and Digg, only 8. ### Google GData ``` | Code | Explanation | |------|-------------| | 200 | OK | | 201 | Created | | 304 | Not Modified | | 400 | Bad Request | | 401 | Unauthorized| | 403 | Forbidden | | 404 | Not Found | | 409 | Conflict | | 410 | Gone | | 500 | Internal Server Error | ``` ### Netflix ``` | Code | Explanation | |------|-------------| | 200 | OK | | 201 | Created | | 304 | Not Modified | | 400 | Bad Request | | 401 | Unauthorized| | 403 | Forbidden | | 404 | Not Found | | 412 | Precondition Failed | | 500 | Internal Server Error | ``` ### Digg ``` | Code | Explanation | |------|-------------| | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized| | 403 | Forbidden | | 404 | Not Found | | 410 | Gone | | 500 | Internal Server Error | | 503 | Service Unavailable | ``` ### How many status codes should you use for your API? When you boil it down, there are really only 3 outcomes in the interaction between an app and an API: - Everything worked - success - The application did something wrong - client error - The API did something wrong - server error ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 14 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ## How to think about version numbers in a pragmatic way with REST? - Never release an API without a version. Make the version mandatory. - Specify the version with a `v` prefix. Move it all the way to the left in the URL so that it has the highest scope (e.g. `/v1/dogs`). - Use a simple ordinal number. Don't use the dot notation like `v1.2` because it implies a granularity of versioning that doesn't work well with APIs—it's an interface not an implementation. Stick with `v1`, `v2`, and so on. ### How many versions should you maintain? Maintain at least one version back. ### For how long should you maintain a version? Give developers at least one cycle to react before obsoleting a version. Sometimes that's 6 months; sometimes it's 2 years. It depends on your developers' development platform, application type, and application users. For example, mobile apps take longer to rev than Web apps. ## Should version and format be in URLs or headers? There is a strong school of thought about putting format and version in the header. Sometimes people are forced to put the version in the header because they have multiple inter-dependent APIs. That is often a symptom of a bigger problem, namely, they are usually exposing their internal mess instead of creating one, usable API facade on top. That's not to say that putting the version in the header is a symptom of a problematic API design. It's not! In fact, using headers is more correct for many reasons: it leverages existing HTTP standards, it's intellectually consistent with Fielding's vision, it solves some hard real-world problems related to inter-dependent APIs, and more. However, we think the reason most of the popular APIs do not use it is because it's less fun to hack in a browser. ### Simple rules we follow: 1. If it changes the logic you write to handle the response, put it in the URL so you can see it easily. 2. If it doesn't change the logic for each response, like OAuth information, put it in the header. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 15 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love These, for example, all represent the same resource: ``` GET /dogs/1 Content-Type: application/json ``` ``` GET /dogs/1 Content-Type: application/xml ``` ``` GET /dogs/1 Content-Type: application/png ``` The code we would write to handle the responses would be very different. There’s no question the header is more correct, and it is still a very strong API design. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 22 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love This results in code that looks like the following, allowing the JavaScript developer to write it in a way that makes sense for JavaScript. ```javascript "createdAt": 1320296464; timing = myObject.createdAt; ``` ## Tips for Search While a simple search could be modeled as a resourceful API (for example, `/dogs/?q=red`), a more complex search across multiple resources requires a different design. This will sound familiar if you've read the topic about using verbs not nouns when results don't return a resource from the database - rather the result is some action or calculation. If you want to do a global search across resources, we suggest you follow the Google model: ### Global Search `/search?q=fluffy+fur` Here, `search` is the verb; `q` represents the query. ### Scoped Search To add scope to your search, you can prepend with the scope of the search. For example, search in dogs owned by resource ID 5678: `/owners/5678/dogs?q=fluffy+fur` Notice that we've dropped the explicit search in the URL and rely on the parameter `q` to indicate the scoped query. (Big thanks to the contributors on the [API Craft](https://apicraft.com) Google group for helping refine this approach.) ### Formatted Results For search or for any of the action-oriented (non-resource) responses, you can prepend with the format as follows: `/search.xml?q=fluffy+fur` ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 35 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love The developer and the app that consume the API are on top. The API façade isolates the developer and the application and the API. Making a clean design in the façade allows you to decompose one really hard problem into a few simpler problems. > “Use the façade pattern when you want to provide a simple interface to a complex subsystem. Subsystems often get more complex as they evolve.” > — Design Patterns – Elements of Reusable Object-Oriented Software > (Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides) Implementing an API façade pattern involves three basic steps: 1. **Design the ideal API** – design the URLs, request parameters and responses, payloads, headers, query parameters, and so on. The API design should be self-consistent. 2. **Implement the design with data stubs**. This allows application developers to use your API and give you feedback even before your API is connected to internal systems. 3. **Mediate or integrate between the façade and the systems.** ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 36 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ![Web API Design Icon](link-to-icon) ## Ideal Design ![Ideal Design Diagram](link-to-ideal-design-diagram) ## API Facade ![API Facade Diagram](link-to-api-facade-diagram) ## Mediate | Big System | DB | Content Mgmt | SOAP | JDBC | RSS | |------------|----|---------------|------|------|-----| Using the three-step approach, you've decomposed one big problem into three smaller problems. If you try to solve the one big problem, you’ll be starting in code and trying to build up from your business logic (systems of record) to a clean API interface. You would be exposing objects or tables or RSS feeds from each silo, mapping each to XML in the right format before exposing to the app. It is a machine-to-machine orientation focused around an app and is difficult to get this right. Taking the façade pattern approach helps shift the thinking from a silo approach in a number of important ways. First, you can get buy-in around each of the three separate steps and have people more clearly understand how you’re taking a pragmatic approach to the design. Secondly, the orientation shifts from the app to the app developer. The goal becomes to ensure that the app developer can use your API because the design is self-consistent and intuitive. Because of where it is in the architecture, the façade becomes an interesting gateway. You can now have the façade implement the handling of common patterns (for pagination, queries, ordering, sorting, etc.), authentication, authorization, versioning, and so on, uniformly across the API. *(This is a big topic and a full discussion is beyond the scope of this article.)* Other benefits for the API team include being more easily able to adapt to different use cases regardless of whether they are internal developer, partner, or open scenarios. The API team will be able to keep pace with the changing needs of developers, including the ever-changing protocols and languages. It is also easier to extend an API by building out more capability from your enterprise or plugging in additional existing systems. ``` #################### File: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf Page: 37 Context: ```markdown # Web API Design - Crafting Interfaces that Developers Love ## Resources - Representational State Transfer (REST), Roy Thomas Fielding, 2000 - [RESTful API Design Webinar](https://example.com), 2nd edition, Brian Mulloy, 2011 - [Apigee API Tech & Best Practices Blog](https://example.com) - [API Craft](https://example.com) Google Group ## About Brian Mulloy **Brian Mulloy, Apigee** Brian has 15 years of experience ranging from enterprise software to founding a Web startup. He co-founded and was CEO of Swivel, a website for social data analysis. He was President and General Manager of Grand Central, a cloud-based offering for application infrastructure (before we called it the cloud). He was also Director of Product Marketing at BEA Systems. Brian holds a degree in Physics from the University of Michigan. Brian is a frequent contributor on the [Apigee API Tech & Best Practices Blog](https://example.com), the [Apigee YouTube channel](https://example.com), the [API Craft](https://example.com) Google Group, and [Webinars](https://example.com). ``` ########## """QUERY: can you give me a random fact from Web API Design""" Consider the chat history for relevant information. Important: If you find information separated by a | in the context, it is a table formatted in Markdown.Important: Take a look at the QUERY and only the QUERY. If this is vague or unclear, please ignore everything and ask a follow-up question instead! Final Files Sources: Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 1, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 2, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 3, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 4, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 5, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 11, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 14, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 15, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 22, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 35, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 36, Web%20API%20Design%20-%20Brian%20Mulloy%20%28PDF%29.pdf - Page 37 ================================================== **Elapsed Time: 0.00 seconds** ================================================== FINAL ANSWER Answer: A random fact from "Web API Design" is that Google GData API utilizes only 10 status codes. ================================================== **Elapsed Time: 1.91 seconds** ==================================================