Web APIs Concepts & Tools for Web Development & Debugging PDF

Web APIs concepts & tools for Web Development & Debugging Web APIs A Web API (Application Programming Interface) is a set of protocols and tools that allow applications to communicate with each other over the web. APIs act as a bridge between client applications (e.g., a website or mobile app) and...

Web APIs concepts & tools for Web Development & Debugging Web APIs A Web API (Application Programming Interface) is a set of protocols and tools that allow applications to communicate with each other over the web. APIs act as a bridge between client applications (e.g., a website or mobile app) and server-side resources or services. Key Characteristics of Web APIs: Platform-agnostic: Can be used by any programming language or framework that supports HTTP. Enable integration: Allow third-party applications to access features or data of a service without exposing the internal workings. Web APIs Role in Modern Web Development: APIs are the backbone of modern applications, enabling integration between services like payment gateways (e.g., Stripe), messaging platforms (e.g., Twilio), or weather data providers (e.g., OpenWeather). Drive modular design: APIs promote separation of concerns, allowing teams to build reusable and independent components. Accelerate innovation: APIs enable developers to rapidly build applications by leveraging external services (e.g., machine learning APIs or mapping APIs).  Types of APIs: REST, SOAP, GraphQL REST (Representational State Transfer): SOAP (Simple Object Access Protocol): A widely used architectural style for APIs. A protocol-based API, often used in enterprise environments. Stateless and resource-oriented Enforces strict standards and uses XML exclusively for (e.g., /users, /products). Communicates via HTTP methods: GET, POST, messaging. Includes built-in error handling and higher security options. PUT, DELETE. Returns responses in lightweight formats like Example: Used in legacy banking systems. JSON or XML. Types of APIs: REST, SOAP, GraphQL GraphQL GraphQL is a query language for APIs and a runtime for executing those queries by using a type system that defines the data available. It was developed by Facebook in 2012 and open-sourced in 2015, aiming to provide a flexible and efficient alternative to REST APIs. With GraphQL, clients can specify the structure of the data they need, and the server returns exactly that, no more and no less. This eliminates common inefficiencies seen in traditional REST APIs. REST Imagine a scenario where you need to call an API for getting the following information on Social Media: ◦ Get information for a specific information ◦ GET /users/1 ◦ Get information about a post for the specific user ◦ GET /users/1/posts ◦ Get information on the comments for the specific post for the specific user ◦ GET /posts/101/comments REST Imagine a scenario where you need to call an API for getting the following information on Social Media: Get information for a specific user GET /users/1 Get information about a post for the specific user GET /users/1/posts Get information on the comments for the specific post for the specific user GET /posts/101/comments GraphQLImagine a scenario where you need to call an API for getting the following information on Social Media: Request Response GraphQLImagine a scenario where you need to call an API for getting the following information on Social Media: Request Response id: “101” specified GraphQL: Current & Future (1) GraphQL, initially developed by Facebook in 2012 and open-sourced in 2015, has evolved into a pivotal technology in API development. Its trajectory indicates continued growth and adaptation to emerging technological trends. Enterprise Adoption: According to Gartner, GraphQL was implemented in just over 10% of enterprises in 2021, with projections indicating that this figure will rise to over 50% by 2025. Integration with AI: The integration of AI into API ecosystems presents new opportunities for GraphQL. Discussions at GraphQLConf 2023 highlighted the potential for GraphQL to work synergistically with AI-driven systems, suggesting that this combination could redefine data- fetching paradigms. GraphQL: Current & Future (2) Support for Modern Programming Languages: As languages like Rust, Kotlin, and Swift gain prominence, the GraphQL ecosystem is adapting to support these modern programming environments, ensuring its relevance across diverse development platforms. Advancements in Tooling: The GraphiQL team has been actively enhancing the GraphiQL IDE, introducing new features and planning future improvements to better serve the developer community. Governance and Standardization: The future success of GraphQL is closely tied to effective governance. Ensuring that GraphQL implementations are metadata-driven and emphasize configuration over code is crucial for broader enterprise adoption. Introduction to HTTP (RECAP) HTTP HTTP, or Hypertext Transfer Protocol, is the fundamental protocol that powers the web. It enables communication between a client (typically a web browser) and a web server. In simpler terms, HTTP is the set of rules that defines how messages are formatted and transmitted, and how servers and browsers should respond to various commands. When you enter a URL in your browser, the browser sends an HTTP request to the server, which then returns the requested web page or resource, such as text, images, or videos. HTTP is a stateless protocol, which means each request from a client to the server is processed independently, without any knowledge of previous requests. To manage sessions, cookies or other technologies are employed to maintain state over multiple requests. Evolution of HTTP HTTP/1.1 (1997): The most widely adopted version of HTTP. It introduced persistent connections, allowing multiple requests and responses to be sent over a single connection, reducing overhead (but only one request can progress at a time). It also introduced chunked transfer encoding, which allowed servers to send data in pieces, and pipelining, allowing clients to send multiple requests without waiting for each response. HTTP/2 (2015): A major upgrade from HTTP/1.1, this version introduced multiplexing, which allows multiple requests and responses to be transferred simultaneously over a single connection. It also added header compression to reduce the size of transmitted headers and server push, where the server can send resources to the client without an explicit request, reducing load times. HTTP/3 (2018, ongoing): Built on the QUIC transport protocol rather than the traditional TCP (Transmission Control Protocol), HTTP/3 offers faster connections and improved reliability. QUIC includes features such as connection migration, allowing data transfer to continue even when the client's IP address changes (e.g., when moving between networks). HTTP/3 also provides better performance for mobile devices and reduces latency in unstable networks. HTTP as a Request-Response Protocol At its core, HTTP is a request-response protocol, meaning communication between the client and server follows a predictable, structured exchange of messages. The client (usually a web browser or another application) makes a request, and the server responds accordingly HTTP Request An HTTP request is the message sent from the client to the server, asking for specific resources or instructing the server to perform a certain action. Each HTTP request consists of several components: ◦ Method ◦ URL ◦ Headers ◦ Body HTTP Request: Method This indicates the desired action to be performed on the server. Common HTTP methods include: GET: Retrieve data from the server (e.g., fetching a web page or API response). GET requests do not have a body. POST: Send data to the server (e.g., submitting a form or uploading a file). POST requests often have a body containing the data to be sent. PUT: Update or replace existing data on the server. DELETE: Remove data from the server. HEAD: Similar to GET, but only retrieves the headers without the body, used for metadata checks. PATCH: Partially update an existing resource. s" becau se th ey describe what M e th od s a re considered "verb re source , si m il ar to how se The se rv e r sho uld take regarding a action the ribe actions. a sen te n ce d esc verbs in HTTP Request: URL URL (Uniform Resource Locator): This specifies the resource the client wants to interact with, including the domain and path to the resource. For example, in https://example.com/page, the URL directs the server to retrieve the /page resource from the example.com domain. HTTP Request: Headers These are key-value pairs that provide additional information about the request. Some common headers include: Host: Specifies the domain name of the server (e.g., Facebook.com) User-Agent: Information about the client (e.g., the browser or application making the request). Content-Type: Specifies the format of the data being sent (e.g., application/json for JSON data, or text/html for HTML). Authorization: Includes credentials to authenticate the client (e.g., tokens or cookies). Accept: Indicates the types of data the client can handle in the response (e.g., application/json, text/html). HTTP Request: Body This is an optional part of the request, typically present in methods like POST, PUT, and PATCH. The body contains the data that the client wants to send to the server, such as form submissions, JSON payloads, or files. HTTP Responses When the server receives an HTTP request, it processes the request and sends back an HTTP response. This response informs the client of the outcome of the request and provides the requested resource or a message. An HTTP response also consists of several components: ◦ Status Code ◦ Headers ◦ Body HTTP Response: Status Code Status Code: This is a three-digit number that indicates the outcome of the request. The status code is divided into five classes: ◦ 1xx (Informational): Request received, continuing process (e.g., 100 Continue). ◦ 2xx (Success): The request was successful (e.g., 200 OK). ◦ 3xx (Redirection): The client must take additional action to complete the request (e.g., 301 Moved Permanently, 302 Found). ◦ 4xx (Client Error): The request was invalid or there was an error on the client side (e.g., 404 Not Found, 400 Bad Request). ◦ 5xx (Server Error): The server encountered an issue while processing the request (e.g., 500 Internal Server Error). HTTP Response: Headers Similar to the request headers, response headers provide additional information about the server or the returned resource. Common response headers include: ◦ Content-Type: Specifies the format of the returned data (e.g., text/html, application/json). ◦ Content-Length: Indicates the size of the response body in bytes. ◦ Set-Cookie: Instructs the client to store cookies for future requests. ◦ Cache-Control: Informs the client about how the response should be cached. HTTP Response: Body The response body contains the data requested by the client, such as an HTML web page, a JSON object (in the case of APIs), or a file. Not all responses have a body; for instance, HEAD requests and responses with status codes like 204 No Content do not include a body. Small Recap HTTP Request HTTP Response Method Status Code URL Send to Server Header Header Body Body More examples on Status Codes Some status codes are provided in the next few slides. Examples are focussed on an aquarium use case. Links are dummy links.  Status Code (2xx): Success Status Example Explanation Request URL Code Scenario The request succeeded, and the Retrieve tank GET https://dummy-api.odysseo- 200 OK mauritius.com/aquarium/tanks/1 server returns the details. data. Example Response  Status Code (2xx): Success Status Example Explanation Request URL Code Scenario Add a new fish 201 A new resource was POST https://dummy-api.odysseo- species to the Created successfully created. mauritius.com/aquarium/species database. Example Response  Status Code (2xx): Success Status Example Explanation Request URL Code Scenario The request is accepted Schedule a water 202 POST https://dummy-api.odysseo- for processing, not yet change for a Accepted mauritius.com/aquarium/tanks/1/maintenance completed. tank. Example Response  Status Code (2xx): Success Status Example Explanation Request URL Code Scenario The request was Mark a fish as 204 No PUT https://dummy-api.odysseo- successful but returns no transferred to Content mauritius.com/aquarium/tanks/1/fish/456 content. another tank.  Status Code (3xx):Redirection Status Example Explanation Request URL Code Scenario 301 The resource has been Tank details Moved GET https://dummy-api.odysseo- permanently moved to a endpoint Permane mauritius.com/aquarium/tank-details/1 new URL. updated. ntly Location: Redirect Header: https://dummy-api.odysseo-mauritius.com/aquarium/tanks/ 1  Status Code (3xx): Redirection Status Example Explanation Request URL Code Scenario The resource is A promotional 302 GET https://dummy-api.odysseo- temporarily moved to page redirects to mauritius.com/specials/current Found another location. a special exhibit. Location: Location: Redirect Header: https://dummy-api.odysseo-mauritius.com/exhibits/shark-week  Status Code (3xx): Redirection Status Example Explanation Request URL Code Scenario The resource has not Check if tank 304 Not GET https://dummy-api.odysseo- been modified since data has been mauritius.com/aquarium/tanks/1 Modified the last request. updated. (No content, only status code returned)  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario The request is invalid Submit invalid 400 Bad POST https://dummy-api.odysseo- due to malformed tank mauritius.com/aquarium/tanks Request syntax or input. dimensions. Example Response  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario 401 Authentication is required Access tank data GET https://dummy-api.odysseo- Unauthor but not provided or without logging mauritius.com/aquarium/tanks/1 ized invalid. in. Example Response  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario 403 A viewer role The user is authenticated DELETE https://dummy-api.odysseo- Forbidde user tries to but lacks permission. mauritius.com/aquarium/tanks/1 n delete a tank. Example Response  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario The requested Try to retrieve 404 Not GET https://dummy-api.odysseo- resource could not be a non-existent mauritius.com/aquarium/species/999 Found found. species. Example Response  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario 405 Attempt to use Method The HTTP method is not POST https://dummy-api.odysseo- POST on a read- Not allowed for the resource. mauritius.com/aquarium/tanks only endpoint. Allowed Example Response  Status Code (4xx): Client Errors Status Example Explanation Request URL Code Scenario The request conflicts with Assign a fish to a 409 POST https://dummy-api.odysseo- the resource's current tank that is Conflict mauritius.com/aquarium/tanks/1/fish state. already full. Example Response  Status Code (5xx): Server Errors Status Example Explanation Request URL Code Scenario 500 A database issue GET Internal The server encountered an prevents fetching https://dummy-api.odysseo-mauritius.com/aquarium/t Server unexpected error. anks/1 tank data. Error Example Response  Status Code (5xx): Server Errors Status Example Explanation Request URL Code Scenario The server received an The main 502 Bad GET https://dummy-api.odysseo- invalid response database is Gateway mauritius.com/aquarium/species upstream. unavailable. Example Response  Status Code (5xx): Server Errors Status Example Explanation Request URL Code Scenario 503 Service The server is temporarily Maintenance is GET https://dummy-api.odysseo- Unavailab unavailable. in progress. mauritius.com/aquarium/tanks le Example Response  Status Code (5xx): Server Errors Status Example Explanation Request URL Code Scenario 504 The server timed out A long-running GET https://dummy-api.odysseo- Gateway waiting for an upstream query timed out. mauritius.com/aquarium/analytics Timeout response. Example Response  Real world Examples – Google Maps API Status Code Explanation Example Scenario Request URL The Google Maps API allows developers Retrieve the geographic GET https://maps.googleapis.com/maps/api/geocode/json? Google Maps to integrate maps, geocoding, routing, coordinates for Port Louis, address=Port+Louis,Mauritius&key=YOUR_API_KEY and places into their applications. Mauritius. Example Response  Real world Examples – Open Weather API Status Example Explanation Request URL Code Scenario OpenWeather API provides real- GET OpenWeather time weather data, forecasts, and Get current weather https://api.openweathermap.org/data/2.5 historical weather information for data for Port Louis. /weather? any location worldwide. q=Port+Louis&appid=YOUR_API_KEY Example Response API Design Principles RESTful API design principles provide guidelines to create APIs that are scalable, easy to understand, and maintainable. By adhering to these principles and referencing the examples of good and bad practices, developers can design RESTful APIs that are intuitive, scalable, and maintainable. Guidelines by Microsoft: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design Guidelines by Postman: https://www.postman.com/api-platform/api-design/ Guidelines by IBM: https://www.ibm.com/topics/rest-apis Guidelines by Amazon Web Services: https://aws.amazon.com/what-is/restful-api/ API Design Principles 1. Resource-Based Endpoints A RESTful API should expose resources through structured, meaningful URLs. Resources are typically nouns (e.g., users, products) and should reflect entities in the application domain. Good Bad /users (Represents all /getUsers (Uses a verb instead of a users) noun) /products/123 (Specific /fetchProductDetails?id=123 (Verb- product by ID) based) /orders/456/items /getItemsForOrder/456 (Action- (Hierarchical structure) oriented)  API Design Principles 2. Use of HTTP Methods REST APIs should utilize standard HTTP methods to represent actions on resources. This ensures consistency and clarity. HTTP Method Use Case Good Bad GET /users/123 POST /getUser GET Retrieve resources (Retrieve user 123) (Wrong method for retrieval) Create new POST POST /users GET /createUser resources (Create a new user) (Encodes action in endpoint) Update existing PUT resources DELETE /users/123 POST /deleteUser/123 (Delete user 123) (Uses POST incorrectly) DELETE Remove resources API Design Principles 3. Statelessness Each API request should contain all necessary information for the server to process it. The server should not store client state between requests. Good Bad A request includes all context: Server stores user session state: - Header: Authorization: Bearer - Client sends incomplete data relying on state - Server maintains filter criteria per - Payload: { "filters": {...} } session API Design Principles 4. Resource Representation Through URLs APIs should use logical and hierarchical URLs to represent resources and sub-resources. Good Bad /users/123/orders /getOrdersForUser?id=123 (Orders for user 123) (Action-based) /stores/456/products /productsByStore?id=456 (Products in store 456) (Verbose query)  API Design Principles 5. Versioning APIs APIs evolve over time, and versioning ensures backward compatibility without breaking existing clients. Good Bad /v1/users /users (Versioned in URL) (No versioning; prone to breaking) /v2/orders /orders (New version for updated behavior) (No clarity on which version applies) API Design Principles 6. Error Handling Provide clear and meaningful responses for errors using appropriate HTTP status codes and messages. Good Bad Status Code: Status Code: 404 Not Found 200 OK with error message in body Response: Response: { { "status": "error", "error": "Resource not found", "message": "User not found" "message": "User ID not found" } } API Design Principles 7. Query Parameters for Filtering Use query parameters for optional filters, sorting, or pagination. This keeps URLs concise and meaningful. Good Bad /products? /products/electronics/sort/price_desc category=electronics&sort=price_desc /users?role=admin&page=1&limit=20 /getAdminUsers?page=1&limit=20 API Design Principles 8. Consistent Naming API resources and endpoints should use consistent and meaningful names, ideally in plural form. Good Bad /users /user (Plural, consistent) (Singular, inconsistent) /products /productList (Descriptive resource name) (Unnecessarily verbose) API Design Principles 9. Response Payloads Responses should provide structured, clear, and meaningful data. Avoid redundancy or returning unnecessary details. Good Bad Response: Response: { "id": 123, "name": "John Doe", ["123", "John Doe", "[email protected]"] "email": "[email protected]" } API Design Principles 10. Pagination For endpoints returning large datasets, paginate results to avoid overwhelming clients and the server. Good Bad Paginated response with metadata: Return all data in one response: { [ "data": [...], { "id": 1, "name": "Product "meta": { "page": 1, "limit": 20, "total": 50 } A" }, } { "id": 2, "name": "Product B" } ] Tools for API Development & Debugging Postman: API Testing and Collaboration Postman is a popular tool for API development and testing that provides a user-friendly interface to send requests to APIs and analyse responses. It supports a wide range of request types such as GET, POST, PUT, DELETE, and more, making it versatile for API interaction. Key features: Testing and Debugging: Allows creating test scripts to validate API responses, ensuring they meet expected behaviour. Collaboration: Teams can share API collections and collaborate in real time using the Postman cloud. Environment Variables: Simplifies testing APIs across different environments (e.g., development, staging, production). Automation: Supports automated testing through its Newman CLI. Review exercises from week 1 (inspecting http requests in real websites) Unsure how this works? Setting up Environment Week 2 Week 5 Exercise 2 Browser Developer Tools: Inspecting Network Calls Browser Developer Tools, such as those provided by Chrome or Firefox, are indispensable for inspecting API calls made by a web application. The Network tab allows developers to observe real-time HTTP requests and responses between the browser and server. Key uses: Debugging: Identify issues such as incorrect endpoints, failed authentication, or slow API responses. Headers and Payloads: Analyse request headers, response headers, and the payload sent or received. Performance Analysis: Track the time taken for API calls and optimize for better performance. Review exercises from week 1 Unsure how this works? (inspecting http requests in real websites) Setting up Environment Week 2 Week 5 Exercise 2 cURL: Command-Line Interaction with APIs cURL is a lightweight and powerful command-line tool used to interact with APIs. It is especially useful for quick testing or debugging when a graphical interface is unnecessary or unavailable. Key capabilities: Versatility: Supports all HTTP methods and allows specifying headers, authentication, and body content directly in the terminal. Scripting: Automates API testing in scripts, enabling integration into CI/CD pipelines. Raw Response Access: Quickly observe raw HTTP responses to debug issues. Unsure how this works? Setting up Environment Week 2 Week 5 Exercise 2 Swagger/OpenAPI: Documenting and Testing APIs Swagger, now part of the OpenAPI Specification (OAS), is a framework for designing, documenting, and testing APIs. A well-documented API improves usability and streamlines onboarding for developers. Key features: Interactive Documentation: Swagger UI allows developers to explore and test API endpoints directly within the browser. Standardized Specification: OpenAPI Specification (OAS) provides a standard way to describe APIs, ensuring consistency. Code Generation: Generates client libraries, server stubs, and API documentation automatically. Setting up Environment Week 2 Unsure how this works? Week 5 Exercise 2