Like 0
Fork 0

Last active 1741698978

Useful to see both Java and Python examples of API usage

kristofer's Avatar kristofer revised this gist 1741698978. Go to revision

1 file changed, 3887 insertions

APIIntro.md(file created)

@@ -0,0 +1,3887 @@
1 + # Explaining APIs to Beginner Programmers
2 +
3 + Here is an explaination APIs to beginner programmers with examples in both Java and Python.
4 + APIs (Application Programming Interfaces) are indeed a fundamental concept for new programmers to understand.
5 +
6 + ## What is an API?
7 +
8 + An API is like a contract between different software components that defines how they should interact.
9 + Think of it as a menu at a restaurant - you don't need to know how the kitchen prepares the food,
10 + you just need to know what you can order and how to place that order.
11 +
12 + ## A Great Public API for Beginners
13 +
14 + The **OpenWeatherMap API** is perfect for beginners because:
15 + - It's free to use (with registration)
16 + - It has straightforward endpoints
17 + - The responses are easy to understand
18 + - It's well-documented
19 + - It works well with both Java and Python
20 +
21 + Let me show you how to use this API in both languages.
22 +
23 + ### Step 1: Get an API Key
24 +
25 + First, register at [OpenWeatherMap](https://openweathermap.org/api) to get a free API key.
26 +
27 + ### Step 2: Make API Calls
28 +
29 + #### Python Example:
30 +
31 + ```python
32 + import requests
33 +
34 + def get_weather(city, api_key):
35 + """
36 + Get current weather for a city using OpenWeatherMap API
37 + """
38 + base_url = "https://api.openweathermap.org/data/2.5/weather"
39 +
40 + # Parameters for our API request
41 + params = {
42 + "q": city,
43 + "appid": api_key,
44 + "units": "metric" # For Celsius
45 + }
46 +
47 + # Make the API call
48 + response = requests.get(base_url, params=params)
49 +
50 + # Check if the request was successful
51 + if response.status_code == 200:
52 + data = response.json() # Convert response to Python dictionary
53 +
54 + # Extract relevant information
55 + weather_description = data["weather"][0]["description"]
56 + temperature = data["main"]["temp"]
57 + humidity = data["main"]["humidity"]
58 +
59 + print(f"Weather in {city}:")
60 + print(f"Description: {weather_description}")
61 + print(f"Temperature: {temperature}°C")
62 + print(f"Humidity: {humidity}%")
63 + else:
64 + print(f"Error: {response.status_code}")
65 + print(response.text)
66 +
67 + # Example usage
68 + if __name__ == "__main__":
69 + city = "London"
70 + api_key = "your_api_key_here" # Replace with actual API key
71 + get_weather(city, api_key)
72 + ```
73 +
74 + #### Java Example:
75 +
76 + ```java
77 + import java.io.BufferedReader;
78 + import java.io.InputStreamReader;
79 + import java.net.HttpURLConnection;
80 + import java.net.URL;
81 + import java.net.URLEncoder;
82 + import java.nio.charset.StandardCharsets;
83 + import org.json.JSONObject; // Requires JSON library (e.g., org.json)
84 +
85 + public class WeatherAPI {
86 +
87 + public static void main(String[] args) {
88 + String city = "London";
89 + String apiKey = "your_api_key_here"; // Replace with actual API key
90 +
91 + try {
92 + getWeather(city, apiKey);
93 + } catch (Exception e) {
94 + e.printStackTrace();
95 + }
96 + }
97 +
98 + public static void getWeather(String city, String apiKey) throws Exception {
99 + // Create URL with parameters
100 + String encodedCity = URLEncoder.encode(city, StandardCharsets.UTF_8);
101 + String urlString = "https://api.openweathermap.org/data/2.5/weather" +
102 + "?q=" + encodedCity +
103 + "&appid=" + apiKey +
104 + "&units=metric";
105 +
106 + URL url = new URL(urlString);
107 +
108 + // Open connection
109 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
110 + connection.setRequestMethod("GET");
111 +
112 + // Check response code
113 + int responseCode = connection.getResponseCode();
114 +
115 + if (responseCode == 200) {
116 + // Read response
117 + BufferedReader reader = new BufferedReader(
118 + new InputStreamReader(connection.getInputStream()));
119 + StringBuilder response = new StringBuilder();
120 + String line;
121 +
122 + while ((line = reader.readLine()) != null) {
123 + response.append(line);
124 + }
125 + reader.close();
126 +
127 + // Parse JSON
128 + JSONObject data = new JSONObject(response.toString());
129 + JSONObject main = data.getJSONObject("main");
130 + JSONObject weather = data.getJSONArray("weather").getJSONObject(0);
131 +
132 + // Extract information
133 + String description = weather.getString("description");
134 + double temperature = main.getDouble("temp");
135 + int humidity = main.getInt("humidity");
136 +
137 + System.out.println("Weather in " + city + ":");
138 + System.out.println("Description: " + description);
139 + System.out.println("Temperature: " + temperature + "°C");
140 + System.out.println("Humidity: " + humidity + "%");
141 + } else {
142 + System.out.println("Error: " + responseCode);
143 + }
144 +
145 + connection.disconnect();
146 + }
147 + }
148 + ```
149 +
150 + ## Key API Concepts to Teach
151 +
152 + 1. **API Endpoints**: The specific URLs that accept requests
153 + 2. **Authentication**: How to use API keys for access
154 + 3. **Request Parameters**: How to customize what data you want
155 + 4. **HTTP Methods**: GET, POST, PUT, DELETE and their purposes
156 + 5. **Response Formats**: Usually JSON or XML
157 + 6. **Status Codes**: Understanding what 200, 404, 500, etc. mean
158 + 7. **Error Handling**: What to do when things go wrong
159 +
160 + ## Additional API Suggestions for Beginners
161 +
162 + If weather doesn't interest you, here are other beginner-friendly public APIs:
163 +
164 + 1. **NASA APOD API**: Get astronomy pictures of the day
165 + 2. **PokeAPI**: Information about Pokémon
166 + 3. **JSONPlaceholder**: Fake data for testing and prototyping
167 + 4. **Open Trivia Database**: Random trivia questions
168 + 5. **Dog CEO**: Random dog images
169 +
170 + # API Concepts: A Comprehensive Study Guide for Beginners
171 +
172 + ## Introduction
173 +
174 + Application Programming Interfaces (APIs) have become an essential skill for modern programmers. They allow different software systems to communicate with each other, enabling developers to leverage existing services rather than building everything from scratch. This study guide introduces key API concepts with practical examples in both Java and Python to help beginners develop a solid understanding of how APIs work and how to use them effectively.
175 +
176 + ## 1. API Endpoints
177 +
178 + ### What are API Endpoints?
179 +
180 + API endpoints are specific URLs that receive API requests. Think of them as the "front door" to a specific service or resource provided by an API. Each endpoint typically represents a particular function or resource in the system and usually follows a hierarchical structure.
181 +
182 + ### Understanding Endpoint Structure
183 +
184 + API endpoints typically consist of:
185 + - A base URL (e.g., `https://api.openweathermap.org`)
186 + - API version (e.g., `/data/2.5/`)
187 + - The specific resource or function (e.g., `/weather` or `/forecast`)
188 +
189 + For example, OpenWeatherMap offers different endpoints for different weather data:
190 + ```
191 + https://api.openweathermap.org/data/2.5/weather // Current weather data
192 + https://api.openweathermap.org/data/2.5/forecast // 5-day forecast
193 + https://api.openweathermap.org/data/2.5/onecall // Current, minute forecast, hourly forecast, and daily forecast
194 + ```
195 +
196 + ### How to Navigate API Documentation
197 +
198 + When learning a new API, always start with its documentation. Good API documentation will list all available endpoints along with:
199 + - What the endpoint does
200 + - Required parameters
201 + - Optional parameters
202 + - Response format
203 + - Example requests and responses
204 +
205 + For instance, the OpenWeatherMap API documentation will tell you that to get current weather data, you need to use the `/weather` endpoint with a city name or coordinates.
206 +
207 + ### RESTful API Design
208 +
209 + Many modern APIs follow REST (Representational State Transfer) principles, which organize endpoints around resources. RESTful APIs typically use:
210 + - Nouns (not verbs) in endpoint paths to represent resources
211 + - HTTP methods to indicate actions on those resources
212 + - Consistent URL patterns
213 +
214 + For example, a RESTful API for a blog might have endpoints like:
215 + ```
216 + GET /posts // Get all posts
217 + GET /posts/123 // Get a specific post
218 + POST /posts // Create a new post
219 + PUT /posts/123 // Update post 123
220 + DELETE /posts/123 // Delete post 123
221 + GET /posts/123/comments // Get comments for post 123
222 + ```
223 +
224 + ### Practice Exercise
225 +
226 + 1. Visit the documentation for a public API (like OpenWeatherMap, GitHub, or Spotify).
227 + 2. Identify at least three different endpoints.
228 + 3. For each endpoint, note what resource it represents and what information it provides.
229 + 4. Try to identify the pattern in how the endpoints are structured.
230 +
231 + ## 2. Authentication
232 +
233 + ### Why Authentication Matters
234 +
235 + Authentication is the process of verifying who is making the request to an API. It's crucial for:
236 + - Protecting private or sensitive data
237 + - Preventing abuse or misuse of the API
238 + - Tracking usage for rate limiting or billing purposes
239 + - Associating requests with specific users or applications
240 +
241 + Without authentication, anyone could potentially access sensitive data or abuse an API service, causing performance issues or excessive costs.
242 +
243 + ### Common Authentication Methods
244 +
245 + #### API Keys
246 +
247 + The simplest form of authentication, typically sent as a query parameter or header:
248 +
249 + **Python Example:**
250 + ```python
251 + import requests
252 +
253 + api_key = "your_api_key_here"
254 + url = f"https://api.openweathermap.org/data/2.5/weather?q=London&appid={api_key}"
255 +
256 + response = requests.get(url)
257 + ```
258 +
259 + **Java Example:**
260 + ```java
261 + import java.net.URL;
262 + import java.net.HttpURLConnection;
263 +
264 + String apiKey = "your_api_key_here";
265 + URL url = new URL("https://api.openweathermap.org/data/2.5/weather?q=London&appid=" + apiKey);
266 +
267 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
268 + connection.setRequestMethod("GET");
269 + ```
270 +
271 + #### OAuth 2.0
272 +
273 + A more complex authentication protocol used when an application needs to access user data on another service (like logging in with Google):
274 +
275 + **Python Example:**
276 + ```python
277 + import requests
278 + from requests_oauthlib import OAuth2Session
279 +
280 + client_id = "your_client_id"
281 + client_secret = "your_client_secret"
282 + redirect_uri = "your_redirect_uri"
283 + scope = ["profile", "email"] # The permissions you're requesting
284 +
285 + # Step 1: Redirect user to authorization URL
286 + oauth = OAuth2Session(client_id, redirect_uri=redirect_uri, scope=scope)
287 + authorization_url, state = oauth.authorization_url("https://accounts.google.com/o/oauth2/auth")
288 +
289 + # Step 2: Get authorization code from redirect and exchange for token
290 + token = oauth.fetch_token(
291 + "https://accounts.google.com/o/oauth2/token",
292 + client_secret=client_secret,
293 + authorization_response=redirect_response
294 + )
295 +
296 + # Step 3: Use token to access API
297 + response = oauth.get("https://www.googleapis.com/oauth2/v1/userinfo")
298 + ```
299 +
300 + **Java Example (using Spring OAuth):**
301 + ```java
302 + @RestController
303 + public class OAuthController {
304 + @GetMapping("/login")
305 + public String login() {
306 + return "redirect:https://accounts.google.com/o/oauth2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=profile email&response_type=code";
307 + }
308 +
309 + @GetMapping("/callback")
310 + public String callback(@RequestParam String code) {
311 + // Exchange code for token
312 + // Use token to access API
313 + }
314 + }
315 + ```
316 +
317 + #### Bearer Tokens (JWT)
318 +
319 + JSON Web Tokens are a compact, URL-safe means of representing claims between two parties:
320 +
321 + **Python Example:**
322 + ```python
323 + import requests
324 +
325 + token = "your_jwt_token"
326 + headers = {
327 + "Authorization": f"Bearer {token}"
328 + }
329 +
330 + response = requests.get("https://api.example.com/resource", headers=headers)
331 + ```
332 +
333 + **Java Example:**
334 + ```java
335 + URL url = new URL("https://api.example.com/resource");
336 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
337 + connection.setRequestMethod("GET");
338 + connection.setRequestProperty("Authorization", "Bearer " + token);
339 + ```
340 +
341 + ### Securing API Credentials
342 +
343 + Always protect your API credentials:
344 +
345 + 1. **Never hardcode credentials** in your source code, especially in repositories that might become public.
346 + 2. **Use environment variables** to store sensitive information:
347 +
348 + **Python:**
349 + ```python
350 + import os
351 + api_key = os.environ.get("API_KEY")
352 + ```
353 +
354 + **Java:**
355 + ```java
356 + String apiKey = System.getenv("API_KEY");
357 + ```
358 +
359 + 3. **Use configuration files** that are excluded from version control:
360 +
361 + **Python (config.py):**
362 + ```python
363 + # Add config.py to .gitignore
364 + API_KEY = "your_key_here"
365 + ```
366 +
367 + **Java (config.properties):**
368 + ```
369 + # Add config.properties to .gitignore
370 + api.key=your_key_here
371 + ```
372 +
373 + 4. **Implement credential rotation** for production applications, changing keys periodically.
374 +
375 + 5. **Use least privilege** - only request the permissions your application needs.
376 +
377 + ### Practice Exercise
378 +
379 + 1. Register for a free API key from OpenWeatherMap or another public API.
380 + 2. Create a small application that uses your API key to make a request.
381 + 3. Implement at least two different methods of storing your API key securely.
382 + 4. Try implementing a simple request to an API that uses OAuth (like GitHub or Spotify).
383 +
384 + ## 3. Request Parameters
385 +
386 + ### Types of Parameters
387 +
388 + Parameters allow you to customize API requests by providing additional data. Different parameter types serve different purposes:
389 +
390 + #### Query Parameters
391 +
392 + Added to the URL after a question mark (`?`) and separated by ampersands (`&`):
393 +
394 + **Python:**
395 + ```python
396 + import requests
397 +
398 + params = {
399 + "q": "London",
400 + "units": "metric",
401 + "appid": "your_api_key"
402 + }
403 +
404 + response = requests.get("https://api.openweathermap.org/data/2.5/weather", params=params)
405 +
406 + # Resulting URL: https://api.openweathermap.org/data/2.5/weather?q=London&units=metric&appid=your_api_key
407 + ```
408 +
409 + **Java:**
410 + ```java
411 + import java.net.URL;
412 + import java.net.URLEncoder;
413 + import java.nio.charset.StandardCharsets;
414 +
415 + String city = URLEncoder.encode("London", StandardCharsets.UTF_8);
416 + String apiKey = "your_api_key";
417 + String urlString = "https://api.openweathermap.org/data/2.5/weather" +
418 + "?q=" + city +
419 + "&units=metric" +
420 + "&appid=" + apiKey;
421 +
422 + URL url = new URL(urlString);
423 + ```
424 +
425 + #### Path Parameters
426 +
427 + Embedded directly in the URL path, usually indicated in documentation with curly braces:
428 +
429 + **Python:**
430 + ```python
431 + import requests
432 +
433 + user_id = "12345"
434 + response = requests.get(f"https://api.github.com/users/{user_id}/repos")
435 + ```
436 +
437 + **Java:**
438 + ```java
439 + String userId = "12345";
440 + URL url = new URL("https://api.github.com/users/" + userId + "/repos");
441 + ```
442 +
443 + #### Header Parameters
444 +
445 + Sent in the HTTP request headers, commonly used for authentication, content type, or custom API features:
446 +
447 + **Python:**
448 + ```python
449 + import requests
450 +
451 + headers = {
452 + "Authorization": "Bearer your_token",
453 + "Content-Type": "application/json",
454 + "Accept-Language": "en-US"
455 + }
456 +
457 + response = requests.get("https://api.example.com/resource", headers=headers)
458 + ```
459 +
460 + **Java:**
461 + ```java
462 + URL url = new URL("https://api.example.com/resource");
463 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
464 + connection.setRequestMethod("GET");
465 + connection.setRequestProperty("Authorization", "Bearer your_token");
466 + connection.setRequestProperty("Content-Type", "application/json");
467 + connection.setRequestProperty("Accept-Language", "en-US");
468 + ```
469 +
470 + #### Request Body Parameters
471 +
472 + Used primarily with POST, PUT, and PATCH requests to send larger amounts of data:
473 +
474 + **Python:**
475 + ```python
476 + import requests
477 + import json
478 +
479 + data = {
480 + "title": "New Post",
481 + "content": "This is the content of my new blog post.",
482 + "author_id": 42
483 + }
484 +
485 + headers = {"Content-Type": "application/json"}
486 + response = requests.post(
487 + "https://api.example.com/posts",
488 + data=json.dumps(data),
489 + headers=headers
490 + )
491 + ```
492 +
493 + **Java:**
494 + ```java
495 + URL url = new URL("https://api.example.com/posts");
496 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
497 + connection.setRequestMethod("POST");
498 + connection.setRequestProperty("Content-Type", "application/json");
499 + connection.setDoOutput(true);
500 +
501 + String jsonInputString = "{\"title\":\"New Post\",\"content\":\"This is the content of my new blog post.\",\"author_id\":42}";
502 +
503 + try(OutputStream os = connection.getOutputStream()) {
504 + byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
505 + os.write(input, 0, input.length);
506 + }
507 + ```
508 +
509 + ### Required vs. Optional Parameters
510 +
511 + API documentation typically distinguishes between:
512 + - **Required parameters**: Must be included for the request to succeed
513 + - **Optional parameters**: Provide additional functionality but can be omitted
514 +
515 + Understanding this distinction helps prevent errors and allows for more flexibility in your API calls.
516 +
517 + ### Parameter Validation
518 +
519 + Before sending an API request, validate your parameters to avoid errors:
520 + 1. Check required parameters are present
521 + 2. Ensure parameters meet format requirements (e.g., date formats, numeric ranges)
522 + 3. Handle special characters by proper encoding
523 +
524 + **Python Example:**
525 + ```python
526 + def validate_weather_params(city=None, lat=None, lon=None):
527 + """Validate parameters for weather API call"""
528 + if city is None and (lat is None or lon is None):
529 + raise ValueError("Either city name or coordinates (lat and lon) must be provided")
530 +
531 + if lat is not None and (lat < -90 or lat > 90):
532 + raise ValueError("Latitude must be between -90 and 90")
533 +
534 + if lon is not None and (lon < -180 or lon > 180):
535 + raise ValueError("Longitude must be between -180 and 180")
536 + ```
537 +
538 + **Java Example:**
539 + ```java
540 + public void validateWeatherParams(String city, Double lat, Double lon) throws IllegalArgumentException {
541 + if (city == null && (lat == null || lon == null)) {
542 + throw new IllegalArgumentException("Either city name or coordinates (lat and lon) must be provided");
543 + }
544 +
545 + if (lat != null && (lat < -90 || lat > 90)) {
546 + throw new IllegalArgumentException("Latitude must be between -90 and 90");
547 + }
548 +
549 + if (lon != null && (lon < -180 || lon > 180)) {
550 + throw new IllegalArgumentException("Longitude must be between -180 and 180");
551 + }
552 + }
553 + ```
554 +
555 + ### Handling Default Values
556 +
557 + When parameters are optional, they often have default values. Understanding these defaults is important:
558 +
559 + ```python
560 + def get_weather(city, api_key, units="metric", lang="en"):
561 + """
562 + Get weather information where:
563 + - units defaults to metric (Celsius)
564 + - language defaults to English
565 + """
566 + params = {
567 + "q": city,
568 + "appid": api_key,
569 + "units": units,
570 + "lang": lang
571 + }
572 +
573 + response = requests.get("https://api.openweathermap.org/data/2.5/weather", params=params)
574 + return response.json()
575 + ```
576 +
577 + ### Practice Exercise
578 +
579 + 1. Choose an API you're interested in and identify its different parameter types.
580 + 2. Create a function that validates parameters before making an API call.
581 + 3. Experiment with optional parameters to see how they affect the response.
582 + 4. Try sending a request with missing required parameters and observe the error.
583 +
584 + ## 4. HTTP Methods
585 +
586 + ### Understanding REST and CRUD
587 +
588 + HTTP methods align with CRUD (Create, Read, Update, Delete) operations in a RESTful API:
589 +
590 + | HTTP Method | CRUD Operation | Description |
591 + |-------------|---------------|--------------------------------------|
592 + | GET | Read | Retrieve data without modifying it |
593 + | POST | Create | Create a new resource |
594 + | PUT | Update | Replace an entire resource |
595 + | PATCH | Update | Partially update a resource |
596 + | DELETE | Delete | Remove a resource |
597 +
598 + ### GET: Retrieving Data
599 +
600 + GET requests are read-only operations used to retrieve data without changing anything on the server. They should be "safe" (don't change data) and "idempotent" (multiple identical requests have the same effect as a single request).
601 +
602 + **Python:**
603 + ```python
604 + import requests
605 +
606 + # Simple GET request
607 + response = requests.get("https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key")
608 +
609 + # GET with parameters
610 + params = {"q": "London", "appid": "your_api_key"}
611 + response = requests.get("https://api.openweathermap.org/data/2.5/weather", params=params)
612 +
613 + # Print response
614 + data = response.json()
615 + print(f"Current temperature in London: {data['main']['temp']}°C")
616 + ```
617 +
618 + **Java:**
619 + ```java
620 + import java.net.HttpURLConnection;
621 + import java.net.URL;
622 + import java.io.BufferedReader;
623 + import java.io.InputStreamReader;
624 +
625 + // Create URL and open connection
626 + URL url = new URL("https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key");
627 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
628 + connection.setRequestMethod("GET");
629 +
630 + // Read response
631 + BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
632 + StringBuilder response = new StringBuilder();
633 + String line;
634 + while ((line = reader.readLine()) != null) {
635 + response.append(line);
636 + }
637 + reader.close();
638 +
639 + // Process JSON response (requires JSON library like org.json or Jackson)
640 + // Example with org.json:
641 + JSONObject data = new JSONObject(response.toString());
642 + double temp = data.getJSONObject("main").getDouble("temp");
643 + System.out.println("Current temperature in London: " + temp + "°C");
644 + ```
645 +
646 + ### POST: Creating Resources
647 +
648 + POST requests create new resources on the server. They are not idempotent—sending the same POST request multiple times typically creates multiple resources.
649 +
650 + **Python:**
651 + ```python
652 + import requests
653 + import json
654 +
655 + # Data to create a new resource
656 + new_post = {
657 + "title": "Understanding APIs",
658 + "body": "This is a comprehensive guide to APIs...",
659 + "userId": 1
660 + }
661 +
662 + # Set headers
663 + headers = {"Content-Type": "application/json"}
664 +
665 + # Make POST request
666 + response = requests.post(
667 + "https://jsonplaceholder.typicode.com/posts",
668 + data=json.dumps(new_post),
669 + headers=headers
670 + )
671 +
672 + # Check if successful
673 + if response.status_code == 201: # 201 Created
674 + created_post = response.json()
675 + print(f"Created post with ID: {created_post['id']}")
676 + else:
677 + print(f"Error: {response.status_code}")
678 + print(response.text)
679 + ```
680 +
681 + **Java:**
682 + ```java
683 + URL url = new URL("https://jsonplaceholder.typicode.com/posts");
684 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
685 + connection.setRequestMethod("POST");
686 + connection.setRequestProperty("Content-Type", "application/json");
687 + connection.setDoOutput(true);
688 +
689 + // Prepare data
690 + String jsonData = "{\"title\":\"Understanding APIs\",\"body\":\"This is a comprehensive guide to APIs...\",\"userId\":1}";
691 +
692 + // Send data
693 + try (OutputStream os = connection.getOutputStream()) {
694 + byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
695 + os.write(input, 0, input.length);
696 + }
697 +
698 + // Check response
699 + int responseCode = connection.getResponseCode();
700 + if (responseCode == 201) {
701 + // Read and process successful response
702 + // ...
703 + } else {
704 + // Handle error
705 + // ...
706 + }
707 + ```
708 +
709 + ### PUT: Replacing Resources
710 +
711 + PUT requests replace an entire resource with a new version. They are idempotent—sending the same PUT request multiple times has the same effect as sending it once.
712 +
713 + **Python:**
714 + ```python
715 + import requests
716 + import json
717 +
718 + # Updated data
719 + updated_post = {
720 + "id": 1,
721 + "title": "Updated Title",
722 + "body": "This post has been completely replaced.",
723 + "userId": 1
724 + }
725 +
726 + # Set headers
727 + headers = {"Content-Type": "application/json"}
728 +
729 + # Make PUT request
730 + response = requests.put(
731 + "https://jsonplaceholder.typicode.com/posts/1",
732 + data=json.dumps(updated_post),
733 + headers=headers
734 + )
735 +
736 + # Check if successful
737 + if response.status_code == 200:
738 + updated_data = response.json()
739 + print("Resource updated successfully")
740 + else:
741 + print(f"Error: {response.status_code}")
742 + ```
743 +
744 + **Java:**
745 + ```java
746 + URL url = new URL("https://jsonplaceholder.typicode.com/posts/1");
747 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
748 + connection.setRequestMethod("PUT");
749 + connection.setRequestProperty("Content-Type", "application/json");
750 + connection.setDoOutput(true);
751 +
752 + // Prepare data
753 + String jsonData = "{\"id\":1,\"title\":\"Updated Title\",\"body\":\"This post has been completely replaced.\",\"userId\":1}";
754 +
755 + // Send data
756 + try (OutputStream os = connection.getOutputStream()) {
757 + byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
758 + os.write(input, 0, input.length);
759 + }
760 +
761 + // Process response
762 + // ...
763 + ```
764 +
765 + ### PATCH: Partial Updates
766 +
767 + PATCH requests make partial updates to a resource. Unlike PUT, which replaces the entire resource, PATCH only modifies the specified fields.
768 +
769 + **Python:**
770 + ```python
771 + import requests
772 + import json
773 +
774 + # Only the fields we want to update
775 + patch_data = {
776 + "title": "Updated Title Only"
777 + }
778 +
779 + # Set headers
780 + headers = {"Content-Type": "application/json"}
781 +
782 + # Make PATCH request
783 + response = requests.patch(
784 + "https://jsonplaceholder.typicode.com/posts/1",
785 + data=json.dumps(patch_data),
786 + headers=headers
787 + )
788 +
789 + # Check if successful
790 + if response.status_code == 200:
791 + patched_data = response.json()
792 + print("Resource partially updated")
793 + else:
794 + print(f"Error: {response.status_code}")
795 + ```
796 +
797 + **Java:**
798 + ```java
799 + URL url = new URL("https://jsonplaceholder.typicode.com/posts/1");
800 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
801 + connection.setRequestMethod("PATCH");
802 + connection.setRequestProperty("Content-Type", "application/json");
803 + connection.setDoOutput(true);
804 +
805 + // Prepare partial data
806 + String jsonData = "{\"title\":\"Updated Title Only\"}";
807 +
808 + // Send data
809 + try (OutputStream os = connection.getOutputStream()) {
810 + byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
811 + os.write(input, 0, input.length);
812 + }
813 +
814 + // Process response
815 + // ...
816 + ```
817 +
818 + ### DELETE: Removing Resources
819 +
820 + DELETE requests remove resources from the server. They are typically idempotent—once a resource is deleted, subsequent DELETE requests for the same resource often return a 404 Not Found.
821 +
822 + **Python:**
823 + ```python
824 + import requests
825 +
826 + # Make DELETE request
827 + response = requests.delete("https://jsonplaceholder.typicode.com/posts/1")
828 +
829 + # Check if successful
830 + if response.status_code == 200 or response.status_code == 204:
831 + print("Resource deleted successfully")
832 + else:
833 + print(f"Error: {response.status_code}")
834 + print(response.text)
835 + ```
836 +
837 + **Java:**
838 + ```java
839 + URL url = new URL("https://jsonplaceholder.typicode.com/posts/1");
840 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
841 + connection.setRequestMethod("DELETE");
842 +
843 + int responseCode = connection.getResponseCode();
844 + if (responseCode == 200 || responseCode == 204) {
845 + System.out.println("Resource deleted successfully");
846 + } else {
847 + System.out.println("Error: " + responseCode);
848 + // Read error response
849 + // ...
850 + }
851 + ```
852 +
853 + ### The Concept of Idempotence
854 +
855 + An operation is idempotent if performing it multiple times has the same effect as performing it once. This is a critical concept in API design:
856 +
857 + - **Idempotent methods**: GET, PUT, DELETE, HEAD
858 + - **Non-idempotent methods**: POST, PATCH (can be made idempotent with careful design)
859 +
860 + Understanding idempotence helps predict API behavior and design reliable systems, especially when retrying failed requests.
861 +
862 + ### Practice Exercise
863 +
864 + 1. Use a public API like JSONPlaceholder (https://jsonplaceholder.typicode.com/) to practice each HTTP method.
865 + 2. Create a simple client that can perform CRUD operations on a resource.
866 + 3. Observe what happens when you:
867 + - Try to GET a non-existent resource
868 + - DELETE a resource twice
869 + - Send an incomplete payload in a POST request
870 + 4. Write a function that automatically retries idempotent requests but not non-idempotent ones.
871 +
872 + ## 5. Response Formats
873 +
874 + ### JSON: The Standard for Modern APIs
875 +
876 + JSON (JavaScript Object Notation) has become the standard format for API responses due to its simplicity, lightweight nature, and native support in JavaScript. It's also easy to work with in virtually all programming languages.
877 +
878 + #### Structure of JSON
879 +
880 + JSON supports:
881 + - Objects (key-value pairs): `{"name": "John", "age": 30}`
882 + - Arrays: `[1, 2, 3, 4]`
883 + - Strings: `"Hello World"`
884 + - Numbers: `42` or `3.14159`
885 + - Booleans: `true` or `false`
886 + - Null: `null`
887 + - Nested combinations of the above
888 +
889 + #### Parsing JSON in Python
890 +
891 + ```python
892 + import requests
893 + import json
894 +
895 + # Make API request
896 + response = requests.get("https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key")
897 +
898 + # Parse JSON response
899 + weather_data = response.json() # requests has built-in JSON parsing
900 +
901 + # Or manually:
902 + # weather_data = json.loads(response.text)
903 +
904 + # Access nested data
905 + temperature = weather_data["main"]["temp"]
906 + weather_description = weather_data["weather"][0]["description"]
907 +
908 + print(f"Current weather in London: {weather_description}, {temperature}°C")
909 +
910 + # Converting Python objects to JSON
911 + new_data = {
912 + "name": "John",
913 + "languages": ["Python", "Java"],
914 + "active": True
915 + }
916 +
917 + json_string = json.dumps(new_data, indent=2) # Pretty-printed JSON
918 + print(json_string)
919 + ```
920 +
921 + #### Parsing JSON in Java
922 +
923 + Java requires a library for JSON processing. Common options include Jackson, Gson, and org.json:
924 +
925 + ```java
926 + // Using org.json
927 + import org.json.JSONObject;
928 + import org.json.JSONArray;
929 + import java.io.BufferedReader;
930 + import java.io.InputStreamReader;
931 + import java.net.HttpURLConnection;
932 + import java.net.URL;
933 +
934 + // Make API request
935 + URL url = new URL("https://api.openweathermap.org/data/2.5/weather?q=London&appid=your_api_key");
936 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
937 + connection.setRequestMethod("GET");
938 +
939 + // Read response
940 + BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
941 + StringBuilder response = new StringBuilder();
942 + String line;
943 + while ((line = reader.readLine()) != null) {
944 + response.append(line);
945 + }
946 + reader.close();
947 +
948 + // Parse JSON
949 + JSONObject weatherData = new JSONObject(response.toString());
950 + double temperature = weatherData.getJSONObject("main").getDouble("temp");
951 + String weatherDescription = weatherData.getJSONArray("weather").getJSONObject(0).getString("description");
952 +
953 + System.out.println("Current weather in London: " + weatherDescription + ", " + temperature + "°C");
954 +
955 + // Creating JSON
956 + JSONObject newData = new JSONObject();
957 + newData.put("name", "John");
958 + newData.put("active", true);
959 +
960 + JSONArray languages = new JSONArray();
961 + languages.put("Python");
962 + languages.put("Java");
963 + newData.put("languages", languages);
964 +
965 + String jsonString = newData.toString(2); // Pretty-printed JSON
966 + System.out.println(jsonString);
967 + ```
968 +
969 + ### XML: The Legacy Format
970 +
971 + XML (eXtensible Markup Language) is an older format still used in some enterprise APIs. While more verbose than JSON, it has strong validation capabilities through DTD and XML Schema.
972 +
973 + #### Structure of XML
974 +
975 + ```xml
976 + <weatherData>
977 + <location>London</location>
978 + <temperature unit="celsius">15.2</temperature>
979 + <conditions>Partly Cloudy</conditions>
980 + <wind>
981 + <speed unit="mph">8</speed>
982 + <direction>NE</direction>
983 + </wind>
984 + </weatherData>
985 + ```
986 +
987 + #### Parsing XML in Python
988 +
989 + ```python
990 + import requests
991 + import xml.etree.ElementTree as ET
992 +
993 + # Make API request to an XML API
994 + response = requests.get("https://api.example.com/weather/xml?location=London")
995 +
996 + # Parse XML
997 + root = ET.fromstring(response.text)
998 +
999 + # Access elements (example paths)
1000 + location = root.find("location").text
1001 + temperature = root.find("temperature").text
1002 + temp_unit = root.find("temperature").get("unit")
1003 + wind_speed = root.find("wind/speed").text
1004 +
1005 + print(f"Weather in {location}: {temperature}°{temp_unit}")
1006 + ```
1007 +
1008 + #### Parsing XML in Java
1009 +
1010 + ```java
1011 + import javax.xml.parsers.DocumentBuilder;
1012 + import javax.xml.parsers.DocumentBuilderFactory;
1013 + import org.w3c.dom.Document;
1014 + import org.w3c.dom.Element;
1015 + import org.w3c.dom.NodeList;
1016 + import java.io.ByteArrayInputStream;
1017 +
1018 + // Make API request and get XML response
1019 + // ...
1020 +
1021 + // Parse XML
1022 + DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
1023 + DocumentBuilder builder = factory.newDocumentBuilder();
1024 + Document document = builder.parse(new ByteArrayInputStream(response.getBytes()));
1025 +
1026 + // Access elements
1027 + Element rootElement = document.getDocumentElement();
1028 + String location = document.getElementsByTagName("location").item(0).getTextContent();
1029 + Element tempElement = (Element) document.getElementsByTagName("temperature").item(0);
1030 + String temperature = tempElement.getTextContent();
1031 + String tempUnit = tempElement.getAttribute("unit");
1032 +
1033 + System.out.println("Weather in " + location + ": " + temperature + "°" + tempUnit);
1034 + ```
1035 +
1036 + ### Other Response Formats
1037 +
1038 + #### CSV (Comma-Separated Values)
1039 +
1040 + Useful for tabular data:
1041 +
1042 + **Python:**
1043 + ```python
1044 + import requests
1045 + import csv
1046 + from io import StringIO
1047 +
1048 + response = requests.get("https://api.example.com/data.csv")
1049 + csv_data = StringIO(response.text)
1050 + reader = csv.DictReader(csv_data)
1051 +
1052 + for row in reader:
1053 + print(f"Country: {row['country']}, Population: {row['population']}")
1054 + ```
1055 +
1056 + **Java:**
1057 + ```java
1058 + import java.io.BufferedReader;
1059 + import java.io.StringReader;
1060 + import java.util.ArrayList;
1061 + import java.util.Arrays;
1062 + import java.util.List;
1063 +
1064 + String csvData = response.toString();
1065 + BufferedReader reader = new BufferedReader(new StringReader(csvData));
1066 +
1067 + String line;
1068 + String[] headers = reader.readLine().split(","); // Assuming first line has headers
1069 +
1070 + while ((line = reader.readLine()) != null) {
1071 + String[] values = line.split(",");
1072 + System.out.println("Country: " + values[0] + ", Population: " + values[1]);
1073 + }
1074 + ```
1075 +
1076 + #### Binary Data
1077 +
1078 + For files, images, and other non-text data:
1079 +
1080 + **Python:**
1081 + ```python
1082 + import requests
1083 +
1084 + response = requests.get("https://api.example.com/image.jpg", stream=True)
1085 + with open("downloaded_image.jpg", "wb") as f:
1086 + for chunk in response.iter_content(chunk_size=8192):
1087 + f.write(chunk)
1088 + ```
1089 +
1090 + **Java:**
1091 + ```java
1092 + import java.io.InputStream;
1093 + import java.nio.file.Files;
1094 + import java.nio.file.Paths;
1095 + import java.nio.file.StandardCopyOption;
1096 +
1097 + URL url = new URL("https://api.example.com/image.jpg");
1098 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
1099 +
1100 + try (InputStream in = connection.getInputStream()) {
1101 + Files.copy(in, Paths.get("downloaded_image.jpg"), StandardCopyOption.REPLACE_EXISTING);
1102 + }
1103 + ```
1104 +
1105 + ### Content Negotiation
1106 +
1107 + APIs often support multiple formats. You can request a specific format using the `Accept` header:
1108 +
1109 + **Python:**
1110 + ```python
1111 + import requests
1112 +
1113 + # Request JSON format
1114 + headers = {"Accept": "application/json"}
1115 + response = requests.get("https://api.example.com/data", headers=headers)
1116 +
1117 + # Request XML format
1118 + headers = {"Accept": "application/xml"}
1119 + response = requests.get("https://api.example.com/data", headers=headers)
1120 + ```
1121 +
1122 + **Java:**
1123 + ```java
1124 + URL url = new URL("https://api.example.com/data");
1125 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
1126 + connection.setRequestProperty("Accept", "application/json");
1127 + ```
1128 +
1129 + ### Handling Complex Nested Data
1130 +
1131 + Real-world API responses can have deeply nested structures. Use a methodical approach to explore and extract data:
1132 +
1133 + **Python:**
1134 + ```python
1135 + def extract_value(data, path):
1136 + """
1137 + Extract value from nested JSON using a path string like "main.temp" or "weather[0].description"
1138 + """
1139 + parts = path.split(".")
1140 + current = data
1141 +
1142 + for part in parts:
1143 + # Handle array indexing like "weather[0]"
1144 + if "[" in part and "]" in part:
1145 + key, index_str = part.split("[")
1146 + index = int(index_str.replace("]", ""))
1147 + current = current[key][index]
1148 + else:
1149 + current = current[part]
1150 +
1151 + return current
1152 +
1153 + # Example usage
1154 + weather_data = response.json()
1155 + temperature = extract_value(weather_data, "main.temp")
1156 + description = extract_value(weather_data, "weather[0].description")
1157 + ```
1158 +
1159 + ### Practice Exercise
1160 +
1161 + 1. Make requests to an API that supports multiple formats (like JSON and XML).
1162 + 2. Write functions to parse and extract the same information from both formats.
1163 + 3. Create a function that can navigate complex nested data structures.
1164 + 4. Try downloading and saving binary data from an API (like an image).
1165 +
1166 + ## 6. Status Codes
1167 +
1168 + ### Understanding HTTP Status Codes
1169 +
1170 + HTTP status codes are three-digit numbers that inform clients about the result of their request. They are grouped into five classes:
1171 +
1172 + | Range | Category | Description |
1173 + |-------|----------|-------------|
1174 + | 1xx | Informational | Request received, continuing process |
1175 + | 2xx | Success | Request successfully received, understood, and accepted |
1176 + | 3xx | Redirection | Further action needed to complete the request |
1177 + | 4xx | Client Error | Request contains bad syntax or cannot be fulfilled |
1178 + | 5xx | Server Error | Server failed to fulfill a valid request |
1179 +
1180 + ### Common Status Codes and Their Meanings
1181 +
1182 + #### Success Codes (2xx)
1183 +
1184 + - **200 OK**: The request succeeded. The response includes the requested data.
1185 + ```
1186 + GET /users/123 → 200 OK (with user data)
1187 + ```
1188 +
1189 + - **201 Created**: The request succeeded and a new resource was created.
1190 + ```
1191 + POST /users → 201 Created (with the created user data)
1192 + ```
1193 +
1194 + - **204 No Content**: The request succeeded but no content is returned.
1195 + ```
1196 + DELETE /users/123 → 204 No Content
1197 + ```
1198 +
1199 + #### Redirection Codes (3xx)
1200 +
1201 + - **301 Moved Permanently**: The resource has been permanently moved to another location.
1202 + ```
1203 + GET /old-page → 301 Moved Permanently (with Location: /new-page)
1204 + ```
1205 +
1206 + - **304 Not Modified**: The resource hasn't changed since the last request (used with conditional GET).
1207 + ```
1208 + GET /users/123 (with If-None-Match header) → 304 Not Modified
1209 + ```
1210 +
1211 + #### Client Error Codes (4xx)
1212 +
1213 + - **400 Bad Request**: The server cannot process the request due to client error (malformed request, invalid parameters).
1214 + ```
1215 + POST /users (with invalid data) → 400 Bad Request
1216 + ```
1217 +
1218 + - **401 Unauthorized**: Authentication is required and has failed or not been provided.
1219 + ```
1220 + GET /private-resource (without auth) → 401 Unauthorized
1221 + ```
1222 +
1223 + - **403 Forbidden**: The server understood the request but refuses to authorize it.
1224 + ```
1225 + GET /admin-panel (as regular user) → 403 Forbidden
1226 + ```
1227 +
1228 + - **404 Not Found**: The requested resource could not be found.
1229 + ```
1230 + GET /non-existent-page → 404 Not Found
1231 + ```
1232 +
1233 + - **409 Conflict**: The request conflicts with the current state of the server.
1234 + ```
1235 + POST /users (with existing username) → 409 Conflict
1236 + ```
1237 +
1238 + - **429 Too Many Requests**: The user has sent too many requests in a given amount of time (rate limiting).
1239 + ```
1240 + GET /api/data (after exceeding rate limit) → 429 Too Many Requests
1241 + ```
1242 +
1243 + #### Server Error Codes (5xx)
1244 +
1245 + - **500 Internal Server Error**: A generic error message when an unexpected condition was encountered.
1246 + ```
1247 + GET /api/data (when server code fails) → 500 Internal Server Error
1248 + ```
1249 +
1250 + - **502 Bad Gateway**: The server was acting as a gateway or proxy and received an invalid response from the upstream server.
1251 + ```
1252 + GET /api/external-service (when external service is down) → 502 Bad Gateway
1253 + ```
1254 +
1255 + - **503 Service Unavailable**: The server is not ready to handle the request, often due to maintenance or overloading.
1256 + ```
1257 + GET /api/data (during maintenance) → 503 Service Unavailable
1258 + ```
1259 +
1260 + ### Checking Status Codes Before Processing Responses
1261 +
1262 + Always check the status code before attempting to process the response:
1263 +
1264 + **Python:**
1265 + ```python
1266 + import requests
1267 +
1268 + response = requests.get("https://api.example.com/resource")
1269 +
1270 + if response.status_code == 200:
1271 + # Process successful response
1272 + data = response.json()
1273 + print(f"Successfully retrieved data: {data}")
1274 + elif response.status_code == 404:
1275 + print("Resource not found!")
1276 + elif response.status_code == 401:
1277 + print("Authentication required!")
1278 + elif 500 <= response.status_code < 600:
1279 + print(f"Server error occurred: {response.status_code}")
1280 + else:
1281 + print(f"Unexpected status code: {response.status_code}")
1282 + ```
1283 +
1284 + **Java:**
1285 + ```java
1286 + URL url = new URL("https://api.example.com/resource");
1287 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
1288 + connection.setRequestMethod("GET");
1289 +
1290 + int statusCode = connection.getResponseCode();
1291 +
1292 + if (statusCode == 200) {
1293 + // Process successful response
1294 + BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
1295 + // Read and process data
1296 + } else if (statusCode == 404) {
1297 + System.out.println("Resource not found!");
1298 + } else if (statusCode == 401) {
1299 + System.out.println("Authentication required!");
1300 + } else if (statusCode >= 500 && statusCode < 600) {
1301 + System.out.println("Server error occurred: " + statusCode);
1302 + } else {
1303 + System.out.println("Unexpected status code: " + statusCode);
1304 + }
1305 + ```
1306 +
1307 + ### Appropriate Actions for Different Status Codes
1308 +
1309 + Here's how to respond to different status codes programmatically:
1310 +
1311 + | Status Code | Appropriate Action |
1312 + |-------------|-------------------|
1313 + | 200, 201 | Process the returned data |
1314 + | 204 | Consider the operation successful, no data to process |
1315 + | 301, 302 | Follow the redirect (most libraries do this automatically) |
1316 + | 304 | Use cached data |
1317 + | 400 | Fix the request format or parameters |
1318 + | 401 | Provide authentication or get a new token |
1319 + | 403 | Inform user they don't have permission |
1320 + | 404 | Inform user the resource doesn't exist |
1321 + | 429 | Wait and retry after the time specified in the Retry-After header |
1322 + | 500, 502, 503 | Wait and retry with exponential backoff |
1323 +
1324 + ### Status Code Handling Pattern
1325 +
1326 + A pattern for robust status code handling:
1327 +
1328 + **Python:**
1329 + ```python
1330 + import requests
1331 + import time
1332 +
1333 + def make_api_request(url, max_retries=3, backoff_factor=1.5):
1334 + """Make an API request with retry logic for certain status codes"""
1335 + retries = 0
1336 +
1337 + while retries < max_retries:
1338 + try:
1339 + response = requests.get(url)
1340 +
1341 + # Success - return the response
1342 + if 200 <= response.status_code < 300:
1343 + return response
1344 +
1345 + # Client errors - don't retry (except 429)
1346 + elif 400 <= response.status_code < 500 and response.status_code != 429:
1347 + print(f"Client error: {response.status_code}")
1348 + return response
1349 +
1350 + # Rate limiting - honor Retry-After header if present
1351 + elif response.status_code == 429:
1352 + retry_after = int(response.headers.get('Retry-After', 5))
1353 + print(f"Rate limited. Waiting {retry_after} seconds.")
1354 + time.sleep(retry_after)
1355 +
1356 + # Server errors and other cases - exponential backoff
1357 + else:
1358 + wait_time = backoff_factor ** retries
1359 + print(f"Received status {response.status_code}. Retrying in {wait_time:.1f} seconds.")
1360 + time.sleep(wait_time)
1361 +
1362 + except requests.exceptions.RequestException as e:
1363 + # Network errors - exponential backoff
1364 + wait_time = backoff_factor ** retries
1365 + print(f"Request failed: {e}. Retrying in {wait_time:.1f} seconds.")
1366 + time.sleep(wait_time)
1367 +
1368 + retries += 1
1369 +
1370 + # If we got here, we ran out of retries
1371 + raise Exception(f"Failed after {max_retries} retries")
1372 + ```
1373 +
1374 + ### Practice Exercise
1375 +
1376 + 1. Create a function that makes API requests and handles different status codes appropriately.
1377 + 2. Test your function against endpoints that might return various status codes:
1378 + - Request a non-existent resource to get a 404
1379 + - Make many requests in short succession to trigger a 429
1380 + - Try accessing a protected resource without authentication for a 401
1381 + 3. Implement a retry mechanism with exponential backoff for 5xx errors.
1382 + 4. Create a mock API server that returns different status codes and test your client against it.
1383 +
1384 + ## 7. Error Handling
1385 +
1386 + ### The Importance of Robust Error Handling
1387 +
1388 + Error handling is critical when working with APIs because many factors are outside your control:
1389 + - Network connectivity issues
1390 + - API servers going down
1391 + - Rate limiting
1392 + - Authentication problems
1393 + - Invalid input data
1394 + - Changes to the API
1395 +
1396 + A well-designed application anticipates these problems and handles them gracefully, providing a better user experience and preventing application crashes.
1397 +
1398 + ### Types of Errors to Handle
1399 +
1400 + #### Network Errors
1401 +
1402 + When the API is unreachable or the connection fails:
1403 +
1404 + **Python:**
1405 + ```python
1406 + import requests
1407 + import socket
1408 +
1409 + try:
1410 + response = requests.get("https://api.example.com/data", timeout=5)
1411 + response.raise_for_status() # Raises an exception for 4XX/5XX responses
1412 + except requests.exceptions.ConnectionError:
1413 + print("Failed to connect to the server. Check your internet connection.")
1414 + except requests.exceptions.Timeout:
1415 + print("The request timed out. The server might be overloaded or down.")
1416 + except requests.exceptions.TooManyRedirects:
1417 + print("Too many redirects. The URL may be incorrect.")
1418 + except requests.exceptions.HTTPError as err:
1419 + print(f"HTTP error occurred: {err}")
1420 + except Exception as err:
1421 + print(f"An unexpected error occurred: {err}")
1422 + ```
1423 +
1424 + **Java:**
1425 + ```java
1426 + import java.net.HttpURLConnection;
1427 + import java.net.URL;
1428 + import java.net.SocketTimeoutException;
1429 + import java.net.UnknownHostException;
1430 + import java.io.IOException;
1431 +
1432 + try {
1433 + URL url = new URL("https://api.example.com/data");
1434 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
1435 + connection.setConnectTimeout(5000); // 5 seconds
1436 + connection.setReadTimeout(5000); // 5 seconds
1437 + connection.setRequestMethod("GET");
1438 +
1439 + int responseCode = connection.getResponseCode();
1440 + // Process response...
1441 +
1442 + } catch (SocketTimeoutException e) {
1443 + System.out.println("The request timed out. The server might be overloaded or down.");
1444 + } catch (UnknownHostException e) {
1445 + System.out.println("Could not find the host. Check the URL and your internet connection.");
1446 + } catch (IOException e) {
1447 + System.out.println("An I/O error occurred: " + e.getMessage());
1448 + } catch (Exception e) {
1449 + System.out.println("An unexpected error occurred: " + e.getMessage());
1450 + }
1451 + ```
1452 +
1453 + #### Authentication Errors
1454 +
1455 + When credentials are invalid or expired:
1456 +
1457 + **Python:**
1458 + ```python
1459 + def make_authenticated_request(url, api_key):
1460 + try:
1461 + response = requests.get(url, headers={"Authorization": f"Bearer {api_key}"})
1462 +
1463 + if response.status_code == 401:
1464 + # Handle unauthorized error
1465 + print("Authentication failed. Your API key may be invalid or expired.")
1466 + # Potentially refresh the token or prompt for new credentials
1467 + return None
1468 + elif response.status_code == 403:
1469 + print("You don't have permission to access this resource.")
1470 + return None
1471 +
1472 + response.raise_for_status()
1473 + return response.json()
1474 +
1475 + except requests.exceptions.HTTPError as err:
1476 + print(f"HTTP error occurred: {err}")
1477 + return None
1478 + ```
1479 +
1480 + #### Data Validation Errors
1481 +
1482 + When the API returns an error due to invalid input:
1483 +
1484 + **Python:**
1485 + ```python
1486 + def create_user(api_url, user_data):
1487 + try:
1488 + response = requests.post(api_url, json=user_data)
1489 +
1490 + if response.status_code == 400:
1491 + # Parse validation errors
1492 + errors = response.json().get("errors", {})
1493 + print("Validation errors:")
1494 + for field, messages in errors.items():
1495 + for message in messages:
1496 + print(f"- {field}: {message}")
1497 + return None
1498 +
1499 + response.raise_for_status()
1500 + return response.json()
1501 +
1502 + except requests.exceptions.HTTPError as err:
1503 + print(f"HTTP error occurred: {err}")
1504 + return None
1505 + ```
1506 +
1507 + #### Rate Limiting Errors
1508 +
1509 + When you've exceeded the allowed number of requests:
1510 +
1511 + **Python:**
1512 + ```python
1513 + def make_rate_limited_request(url, max_retries=3):
1514 + for attempt in range(max_retries):
1515 + response = requests.get(url)
1516 +
1517 + if response.status_code == 429:
1518 + # Check for Retry-After header
1519 + if "Retry-After" in response.headers:
1520 + wait_seconds = int(response.headers["Retry-After"])
1521 + else:
1522 + wait_seconds = 2 ** attempt # Exponential backoff
1523 +
1524 + print(f"Rate limit exceeded. Waiting {wait_seconds} seconds...")
1525 + time.sleep(wait_seconds)
1526 + continue
1527 +
1528 + return response
1529 +
1530 + print(f"Failed after {max_retries} retries due to rate limiting")
1531 + return None
1532 + ```
1533 +
1534 + ### Implementing Retry Logic
1535 +
1536 + For transient errors (like network issues or server errors), implementing retry logic with exponential backoff is a best practice:
1537 +
1538 + **Python:**
1539 + ```python
1540 + import requests
1541 + import time
1542 + import random
1543 +
1544 + def make_request_with_retry(url, max_retries=5, base_delay=1, max_delay=60):
1545 + """Make a request with exponential backoff retry logic"""
1546 +
1547 + for attempt in range(max_retries):
1548 + try:
1549 + response = requests.get(url, timeout=10)
1550 + response.raise_for_status() # Raise exception for 4xx/5xx status codes
1551 + return response
1552 +
1553 + except (requests.exceptions.RequestException, requests.exceptions.HTTPError) as e:
1554 + # Don't retry for client errors (except for 429 Too Many Requests)
1555 + if hasattr(e, 'response') and 400 <= e.response.status_code < 500 and e.response.status_code != 429:
1556 + print(f"Client error: {e}")
1557 + return e.response
1558 +
1559 + # If we've used all retries, re-raise the exception
1560 + if attempt == max_retries - 1:
1561 + raise
1562 +
1563 + # Calculate delay with exponential backoff and jitter
1564 + delay = min(base_delay * (2 ** attempt) + random.uniform(0, 0.5), max_delay)
1565 +
1566 + print(f"Request failed: {e}. Retrying in {delay:.2f} seconds...")
1567 + time.sleep(delay)
1568 +
1569 + # We shouldn't get here, but just in case
1570 + raise Exception("Retry logic failed")
1571 + ```
1572 +
1573 + **Java:**
1574 + ```java
1575 + public Response makeRequestWithRetry(String urlString, int maxRetries, double baseDelay, double maxDelay)
1576 + throws IOException {
1577 +
1578 + Random random = new Random();
1579 +
1580 + for (int attempt = 0; attempt < maxRetries; attempt++) {
1581 + try {
1582 + URL url = new URL(urlString);
1583 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
1584 + connection.setConnectTimeout(10000);
1585 + connection.setReadTimeout(10000);
1586 +
1587 + int statusCode = connection.getResponseCode();
1588 +
1589 + // Success!
1590 + if (statusCode >= 200 && statusCode < 300) {
1591 + return new Response(statusCode, connection.getInputStream());
1592 + }
1593 +
1594 + // Don't retry client errors (except 429)
1595 + if (statusCode >= 400 && statusCode < 500 && statusCode != 429) {
1596 + System.out.println("Client error: " + statusCode);
1597 + return new Response(statusCode, connection.getErrorStream());
1598 + }
1599 +
1600 + // If we've used all retries, return the error
1601 + if (attempt == maxRetries - 1) {
1602 + return new Response(statusCode, connection.getErrorStream());
1603 + }
1604 +
1605 + // Calculate delay with exponential backoff and jitter
1606 + double delay = Math.min(baseDelay * Math.pow(2, attempt) + random.nextDouble() * 0.5, maxDelay);
1607 +
1608 + System.out.println("Request failed with status " + statusCode + ". Retrying in " +
1609 + String.format("%.2f", delay) + " seconds...");
1610 +
1611 + Thread.sleep((long)(delay * 1000));
1612 +
1613 + } catch (InterruptedException e) {
1614 + Thread.currentThread().interrupt();
1615 + throw new IOException("Request interrupted", e);
1616 + }
1617 + }
1618 +
1619 + // We shouldn't get here, but just in case
1620 + throw new IOException("Retry logic failed");
1621 + }
1622 +
1623 + // Simple response class to hold status code and data
1624 + class Response {
1625 + private int statusCode;
1626 + private InputStream data;
1627 +
1628 + public Response(int statusCode, InputStream data) {
1629 + this.statusCode = statusCode;
1630 + this.data = data;
1631 + }
1632 +
1633 + // Getters...
1634 + }
1635 + ```
1636 +
1637 + ### Logging for Troubleshooting
1638 +
1639 + Implementing proper logging is essential for diagnosing API issues:
1640 +
1641 + **Python:**
1642 + ```python
1643 + import logging
1644 + import requests
1645 +
1646 + # Configure logging
1647 + logging.basicConfig(
1648 + level=logging.INFO,
1649 + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
1650 + filename='api_client.log'
1651 + )
1652 + logger = logging.getLogger('api_client')
1653 +
1654 + def call_api(url, params=None, headers=None):
1655 + """Call API with logging"""
1656 + try:
1657 + logger.info(f"Making request to {url}")
1658 +
1659 + response = requests.get(url, params=params, headers=headers)
1660 +
1661 + # Log based on response status
1662 + if 200 <= response.status_code < 300:
1663 + logger.info(f"Request succeeded: {response.status_code}")
1664 + else:
1665 + logger.warning(f"Request failed with status: {response.status_code}")
1666 + logger.debug(f"Response body: {response.text[:500]}") # Log first 500 chars
1667 +
1668 + return response
1669 +
1670 + except requests.exceptions.RequestException as e:
1671 + logger.error(f"Request error: {e}")
1672 + raise
1673 + ```
1674 +
1675 + ### Creating a Robust API Client Class
1676 +
1677 + Putting it all together in a robust API client class:
1678 +
1679 + **Python:**
1680 + ```python
1681 + import requests
1682 + import time
1683 + import logging
1684 + import json
1685 + import random
1686 +
1687 + class ApiClient:
1688 + def __init__(self, base_url, api_key=None, timeout=10, max_retries=3):
1689 + self.base_url = base_url
1690 + self.api_key = api_key
1691 + self.timeout = timeout
1692 + self.max_retries = max_retries
1693 +
1694 + # Set up logging
1695 + self.logger = logging.getLogger(__name__)
1696 +
1697 + def _get_headers(self):
1698 + """Get headers for requests"""
1699 + headers = {
1700 + "Content-Type": "application/json",
1701 + "Accept": "application/json"
1702 + }
1703 +
1704 + if self.api_key:
1705 + headers["Authorization"] = f"Bearer {self.api_key}"
1706 +
1707 + return headers
1708 +
1709 + def _make_request(self, method, endpoint, params=None, data=None, retry_on_status=None):
1710 + """
1711 + Make an HTTP request with retry logic
1712 +
1713 + Args:
1714 + method (str): HTTP method (get, post, put, delete)
1715 + endpoint (str): API endpoint (without base URL)
1716 + params (dict, optional): Query parameters
1717 + data (dict, optional): Request body for POST/PUT
1718 + retry_on_status (list, optional): Status codes to retry on, defaults to 5xx
1719 +
1720 + Returns:
1721 + requests.Response: Response object
1722 + """
1723 + if retry_on_status is None:
1724 + retry_on_status = [429, 500, 502, 503, 504]
1725 +
1726 + url = f"{self.base_url}/{endpoint.lstrip('/')}"
1727 + headers = self._get_headers()
1728 +
1729 + self.logger.info(f"Making {method.upper()} request to {url}")
1730 +
1731 + if data:
1732 + self.logger.debug(f"Request data: {json.dumps(data)[:500]}")
1733 +
1734 + for attempt in range(self.max_retries):
1735 + try:
1736 + response = requests.request(
1737 + method=method,
1738 + url=url,
1739 + headers=headers,
1740 + params=params,
1741 + json=data if data else None,
1742 + timeout=self.timeout
1743 + )
1744 +
1745 + # Log response info
1746 + self.logger.info(f"Response status: {response.status_code}")
1747 +
1748 + # Return immediately on success or if not a retryable status code
1749 + if response.status_code < 400 or response.status_code not in retry_on_status:
1750 + return response
1751 +
1752 + # If we've used all retries, return the response anyway
1753 + if attempt == self.max_retries - 1:
1754 + return response
1755 +
1756 + # Handle rate limiting
1757 + if response.status_code == 429 and 'Retry-After' in response.headers:
1758 + sleep_time = int(response.headers['Retry-After'])
1759 + else:
1760 + # Exponential backoff with jitter
1761 + sleep_time = (2 ** attempt) + random.uniform(0, 1)
1762 +
1763 + self.logger.warning(
1764 + f"Request failed with status {response.status_code}. "
1765 + f"Retrying in {sleep_time:.2f} seconds..."
1766 + )
1767 +
1768 + time.sleep(sleep_time)
1769 +
1770 + except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e:
1771 + if attempt == self.max_retries - 1:
1772 + self.logger.error(f"Request failed after {self.max_retries} attempts: {e}")
1773 + raise
1774 +
1775 + sleep_time = (2 ** attempt) + random.uniform(0, 1)
1776 + self.logger.warning(f"Request error: {e}. Retrying in {sleep_time:.2f} seconds...")
1777 + time.sleep(sleep_time)
1778 +
1779 + return None # Should never reach here
1780 +
1781 + # Convenience methods for different HTTP methods
1782 + def get(self, endpoint, params=None):
1783 + return self._make_request("get", endpoint, params=params)
1784 +
1785 + def post(self, endpoint, data=None, params=None):
1786 + return self._make_request("post", endpoint, params=params, data=data)
1787 +
1788 + def put(self, endpoint, data=None, params=None):
1789 + return self._make_request("put", endpoint, params=params, data=data)
1790 +
1791 + def delete(self, endpoint, params=None):
1792 + return self._make_request("delete", endpoint, params=params)
1793 + ```
1794 +
1795 + ### Practice Exercise
1796 +
1797 + 1. Implement a comprehensive error handling strategy for an API client.
1798 + 2. Add appropriate logging to track API calls, responses, and errors.
1799 + 3. Test your error handling by:
1800 + - Disconnecting from the internet during a request
1801 + - Providing invalid authentication
1802 + - Sending malformed data
1803 + - Simulating rate limiting
1804 + 4. Extend the `ApiClient` class provided above with more features like:
1805 + - Token refresh functionality
1806 + - Request timeout customization
1807 + - Custom error handling callbacks
1808 +
1809 + ## 8. Rate Limiting
1810 +
1811 + ### Understanding API Rate Limits
1812 +
1813 + Rate limiting restricts how many requests a client can make to an API within a specific time period. API providers implement rate limits to:
1814 + - Prevent abuse and DoS attacks
1815 + - Ensure fair usage among all clients
1816 + - Maintain service stability
1817 + - Create tiered service levels (free vs. paid)
1818 +
1819 + Common rate limit structures include:
1820 + - X requests per second
1821 + - X requests per minute/hour/day
1822 + - Different limits for different endpoints
1823 + - Burst limits vs. sustained limits
1824 +
1825 + ### How Rate Limits Are Communicated
1826 +
1827 + APIs typically communicate rate limits through HTTP headers:
1828 +
1829 + | Header | Description | Example |
1830 + |--------|-------------|---------|
1831 + | X-RateLimit-Limit | Maximum requests allowed in period | `X-RateLimit-Limit: 100` |
1832 + | X-RateLimit-Remaining | Requests remaining in current period | `X-RateLimit-Remaining: 45` |
1833 + | X-RateLimit-Reset | Time when limit resets (Unix timestamp) | `X-RateLimit-Reset: 1612347485` |
1834 + | Retry-After | Seconds to wait before retrying | `Retry-After: 30` |
1835 +
1836 + The exact header names may vary between APIs, so check the documentation.
1837 +
1838 + ### Detecting Rate Limiting
1839 +
1840 + You can detect rate limiting through:
1841 + 1. HTTP status code 429 (Too Many Requests)
1842 + 2. Rate limit headers in the response
1843 + 3. Error messages in the response body
1844 +
1845 + **Python:**
1846 + ```python
1847 + import requests
1848 + import time
1849 +
1850 + def make_request(url):
1851 + response = requests.get(url)
1852 +
1853 + # Check if we're rate limited
1854 + if response.status_code == 429:
1855 + if 'Retry-After' in response.headers:
1856 + retry_after = int(response.headers['Retry-After'])
1857 + print(f"Rate limited. Need to wait {retry_after} seconds.")
1858 + return None, retry_after
1859 + else:
1860 + print("Rate limited. No Retry-After header provided.")
1861 + return None, 60 # Default wait time
1862 +
1863 + # Check remaining limit
1864 + remaining = int(response.headers.get('X-RateLimit-Remaining', 1000))
1865 + reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
1866 +
1867 + current_time = int(time.time())
1868 + time_until_reset = max(0, reset_time - current_time)
1869 +
1870 + print(f"Requests remaining: {remaining}")
1871 + print(f"Rate limit resets in {time_until_reset} seconds")
1872 +
1873 + return response, 0 # No need to wait
1874 + ```
1875 +
1876 + ### Implementing Rate Limit Handling
1877 +
1878 + #### 1. Respecting Retry-After Headers
1879 +
1880 + When rate limited, respect the `Retry-After` header:
1881 +
1882 + **Python:**
1883 + ```python
1884 + def call_api_with_rate_limit_handling(url):
1885 + response = requests.get(url)
1886 +
1887 + if response.status_code == 429:
1888 + if 'Retry-After' in response.headers:
1889 + wait_time = int(response.headers['Retry-After'])
1890 + print(f"Rate limited. Waiting {wait_time} seconds...")
1891 + time.sleep(wait_time)
1892 + # Retry the request
1893 + return call_api_with_rate_limit_handling(url)
1894 + else:
1895 + # No Retry-After header, use default backoff
1896 + print("Rate limited. Using default backoff...")
1897 + time.sleep(30)
1898 + return call_api_with_rate_limit_handling(url)
1899 +
1900 + return response
1901 + ```
1902 +
1903 + #### 2. Proactive Rate Limiting
1904 +
1905 + Instead of waiting for 429 errors, track rate limits proactively:
1906 +
1907 + **Python:**
1908 + ```python
1909 + import time
1910 + import requests
1911 +
1912 + class RateLimitedAPI:
1913 + def __init__(self, base_url, requests_per_minute=60):
1914 + self.base_url = base_url
1915 + self.requests_per_minute = requests_per_minute
1916 + self.request_timestamps = []
1917 +
1918 + def make_request(self, endpoint, method="get", **kwargs):
1919 + """Make a rate-limited request"""
1920 + # Clean up old timestamps
1921 + current_time = time.time()
1922 + self.request_timestamps = [ts for ts in self.request_timestamps
1923 + if current_time - ts < 60]
1924 +
1925 + # Check if we're at the limit
1926 + if len(self.request_timestamps) >= self.requests_per_minute:
1927 + # Calculate time to wait
1928 + oldest_timestamp = min(self.request_timestamps)
1929 + wait_time = 60 - (current_time - oldest_timestamp)
1930 +
1931 + if wait_time > 0:
1932 + print(f"Rate limit reached. Waiting {wait_time:.2f} seconds...")
1933 + time.sleep(wait_time)
1934 +
1935 + # Make the request
1936 + url = f"{self.base_url}/{endpoint.lstrip('/')}"
1937 + response = requests.request(method, url, **kwargs)
1938 +
1939 + # Add timestamp
1940 + self.request_timestamps.append(time.time())
1941 +
1942 + # Handle 429 if our proactive limiting fails
1943 + if response.status_code == 429:
1944 + retry_after = int(response.headers.get('Retry-After', 60))
1945 + print(f"Rate limited anyway. Waiting {retry_after} seconds...")
1946 + time.sleep(retry_after)
1947 + return self.make_request(endpoint, method, **kwargs)
1948 +
1949 + return response
1950 + ```
1951 +
1952 + #### 3. Token Bucket Implementation
1953 +
1954 + For more sophisticated rate limiting, implement a token bucket algorithm:
1955 +
1956 + **Python:**
1957 + ```python
1958 + import time
1959 +
1960 + class TokenBucket:
1961 + """Token bucket rate limiter"""
1962 +
1963 + def __init__(self, tokens_per_second, max_tokens):
1964 + self.tokens_per_second = tokens_per_second
1965 + self.max_tokens = max_tokens
1966 + self.tokens = max_tokens
1967 + self.last_refill_time = time.time()
1968 +
1969 + def get_token(self):
1970 + """Try to get a token. Returns True if successful, False otherwise."""
1971 + self._refill()
1972 +
1973 + if self.tokens >= 1:
1974 + self.tokens -= 1
1975 + return True
1976 + else:
1977 + return False
1978 +
1979 + def _refill(self):
1980 + """Refill tokens based on elapsed time"""
1981 + now = time.time()
1982 + elapsed = now - self.last_refill_time
1983 + new_tokens = elapsed * self.tokens_per_second
1984 +
1985 + if new_tokens > 0:
1986 + self.tokens = min(self.tokens + new_tokens, self.max_tokens)
1987 + self.last_refill_time = now
1988 +
1989 + def wait_for_token(self):
1990 + """Wait until a token is available and then use it"""
1991 + while not self.get_token():
1992 + # Calculate time until next token
1993 + time_to_wait = (1 - self.tokens) / self.tokens_per_second
1994 + time.sleep(max(0.01, time_to_wait)) # Minimum wait to avoid busy loop
1995 + return True
1996 + ```
1997 +
1998 + ### Handling Multiple Rate Limits
1999 +
2000 + Some APIs have different rate limits for different endpoints. You can implement a system to track multiple limits:
2001 +
2002 + **Python:**
2003 + ```python
2004 + class MultiRateLimiter:
2005 + """Handles multiple rate limits (global and per-endpoint)"""
2006 +
2007 + def __init__(self):
2008 + # Global limiter (e.g., 1000 requests per hour)
2009 + self.global_limiter = TokenBucket(1000/3600, 1000)
2010 +
2011 + # Per-endpoint limiters
2012 + self.endpoint_limiters = {
2013 + "search": TokenBucket(30/60, 30), # 30 per minute
2014 + "users": TokenBucket(300/60, 300), # 300 per minute
2015 + # Add more endpoints as needed
2016 + }
2017 +
2018 + def wait_for_request(self, endpoint):
2019 + """Wait until request can be made for this endpoint"""
2020 + # First check global limit
2021 + self.global_limiter.wait_for_token()
2022 +
2023 + # Then check endpoint-specific limit if it exists
2024 + if endpoint in self.endpoint_limiters:
2025 + self.endpoint_limiters[endpoint].wait_for_token()
2026 + ```
2027 +
2028 + ### Practice Exercise
2029 +
2030 + 1. Create a rate-limited API client that respects the rate limits of a public API.
2031 + 2. Implement the token bucket algorithm and use it to limit your requests.
2032 + 3. Write code to parse and utilize rate limit headers from responses.
2033 + 4. Test your implementation by making many requests and observing how your client throttles itself to avoid 429 errors.
2034 + 5. Create a visualization (console output or graph) showing your request rate over time.
2035 +
2036 + ## 9. Versioning
2037 +
2038 + ### Why API Versioning Matters
2039 +
2040 + API versioning allows providers to evolve their APIs without breaking existing client applications. Without versioning, any change to an API could potentially break all clients using it. Versioning gives both API providers and consumers a smooth transition path when changes are necessary.
2041 +
2042 + Key benefits of versioning:
2043 + - Allows introduction of new features
2044 + - Enables deprecating or removing outdated functionality
2045 + - Provides backward compatibility for existing clients
2046 + - Allows major architectural changes over time
2047 + - Helps with documentation and support
2048 +
2049 + ### Common Versioning Strategies
2050 +
2051 + #### 1. URI Path Versioning
2052 +
2053 + Including the version in the URL path:
2054 +
2055 + ```
2056 + https://api.example.com/v1/users
2057 + https://api.example.com/v2/users
2058 + ```
2059 +
2060 + **Python:**
2061 + ```python
2062 + # Client for v1
2063 + v1_client = ApiClient("https://api.example.com/v1")
2064 + response = v1_client.get("users")
2065 +
2066 + # Client for v2
2067 + v2_client = ApiClient("https://api.example.com/v2")
2068 + response = v2_client.get("users")
2069 + ```
2070 +
2071 + **Java:**
2072 + ```java
2073 + // Client for v1
2074 + ApiClient v1Client = new ApiClient("https://api.example.com/v1");
2075 + Response v1Response = v1Client.get("users");
2076 +
2077 + // Client for v2
2078 + ApiClient v2Client = new ApiClient("https://api.example.com/v2");
2079 + Response v2Response = v2Client.get("users");
2080 + ```
2081 +
2082 + #### 2. Query Parameter Versioning
2083 +
2084 + Including the version as a query parameter:
2085 +
2086 + ```
2087 + https://api.example.com/users?version=1
2088 + https://api.example.com/users?version=2
2089 + ```
2090 +
2091 + **Python:**
2092 + ```python
2093 + api_client = ApiClient("https://api.example.com")
2094 +
2095 + # Get v1 data
2096 + response_v1 = api_client.get("users", params={"version": "1"})
2097 +
2098 + # Get v2 data
2099 + response_v2 = api_client.get("users", params={"version": "2"})
2100 + ```
2101 +
2102 + #### 3. HTTP Header Versioning
2103 +
2104 + Using a custom HTTP header to specify the version:
2105 +
2106 + ```
2107 + Accept: application/vnd.example.v1+json
2108 + Accept: application/vnd.example.v2+json
2109 + ```
2110 +
2111 + **Python:**
2112 + ```python
2113 + import requests
2114 +
2115 + # Get v1 data
2116 + headers_v1 = {"Accept": "application/vnd.example.v1+json"}
2117 + response_v1 = requests.get("https://api.example.com/users", headers=headers_v1)
2118 +
2119 + # Get v2 data
2120 + headers_v2 = {"Accept": "application/vnd.example.v2+json"}
2121 + response_v2 = requests.get("https://api.example.com/users", headers=headers_v2)
2122 + ```
2123 +
2124 + **Java:**
2125 + ```java
2126 + // Get v1 data
2127 + URL url = new URL("https://api.example.com/users");
2128 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
2129 + connection.setRequestProperty("Accept", "application/vnd.example.v1+json");
2130 + ```
2131 +
2132 + #### 4. Content Type Versioning
2133 +
2134 + Embedding the version in the content type:
2135 +
2136 + ```
2137 + Content-Type: application/json; version=1
2138 + Content-Type: application/json; version=2
2139 + ```
2140 +
2141 + ### Handling API Version Changes
2142 +
2143 + When an API you're using releases a new version, follow these steps:
2144 +
2145 + 1. **Read the Changelog**: Understand what's changed and why.
2146 + 2. **Review Deprecated Features**: Identify any methods or parameters you're using that will be deprecated.
2147 + 3. **Test With Both Versions**: Test your application against both the old and new versions in a development environment.
2148 + 4. **Update Your Code**: Make necessary changes to support the new version.
2149 + 5. **Implement Fallback Logic**: Consider having fallback code that can work with multiple versions.
2150 +
2151 + **Python Example with Version Fallback:**
2152 + ```python
2153 + def get_user_data(user_id):
2154 + """Get user data with fallback to older API version if needed"""
2155 + # Try latest version first
2156 + try:
2157 + headers = {"Accept": "application/vnd.example.v2+json"}
2158 + response = requests.get(f"https://api.example.com/users/{user_id}", headers=headers)
2159 +
2160 + # If successful, parse v2 response format
2161 + if response.status_code == 200:
2162 + data = response.json()
2163 + return {
2164 + "id": data["id"],
2165 + "name": data["display_name"], # v2 uses display_name
2166 + "email": data["email_address"] # v2 uses email_address
2167 + }
2168 + except Exception as e:
2169 + print(f"Error with v2 API: {e}")
2170 +
2171 + # Fallback to v1
2172 + try:
2173 + headers = {"Accept": "application/vnd.example.v1+json"}
2174 + response = requests.get(f"https://api.example.com/users/{user_id}", headers=headers)
2175 +
2176 + # Parse v1 response format
2177 + if response.status_code == 200:
2178 + data = response.json()
2179 + return {
2180 + "id": data["id"],
2181 + "name": data["name"], # v1 uses name
2182 + "email": data["email"] # v1 uses email
2183 + }
2184 + except Exception as e:
2185 + print(f"Error with v1 API: {e}")
2186 +
2187 + return None # Both versions failed
2188 + ```
2189 +
2190 + ### Versioning Best Practices
2191 +
2192 + 1. **Semantic Versioning**: Follow the MAJOR.MINOR.PATCH pattern where:
2193 + - MAJOR: Breaking changes
2194 + - MINOR: New features, backwards-compatible
2195 + - PATCH: Bug fixes, backwards-compatible
2196 +
2197 + 2. **Maintain Multiple Versions**: Keep older versions running during transition periods.
2198 +
2199 + 3. **Clear Deprecation Policy**: Communicate when old versions will be discontinued.
2200 +
2201 + 4. **Version-Specific Documentation**: Maintain separate documentation for each version.
2202 +
2203 + 5. **Version in Responses**: Include version information in API responses for debugging.
2204 +
2205 + ### Practice Exercise
2206 +
2207 + 1. Find a public API that supports multiple versions (GitHub, Twitter, etc.).
2208 + 2. Write a client that can work with two different versions of the API.
2209 + 3. Create a function that automatically detects which version of an API is available and adapts accordingly.
2210 + 4. Design your own simple API and create a version upgrade strategy, including what would change between versions.
2211 +
2212 + ## 10. Documentation and Testing
2213 +
2214 + ### Understanding API Documentation
2215 +
2216 + Good API documentation is essential for developers to effectively use an API. It typically includes:
2217 +
2218 + 1. **Getting Started Guide**: Basic information on authentication and making your first request
2219 + 2. **Reference Documentation**: Details of each endpoint, including:
2220 + - URL structure
2221 + - HTTP method
2222 + - Required and optional parameters
2223 + - Request and response formats
2224 + - Example requests and responses
2225 + - Error codes and messages
2226 + 3. **Tutorials and Use Cases**: Common scenarios and how to implement them
2227 + 4. **SDKs and Client Libraries**: Official libraries for different programming languages
2228 + 5. **Change Log**: History of API changes and version differences
2229 +
2230 + ### How to Read API Documentation
2231 +
2232 + Reading API documentation effectively is a skill:
2233 +
2234 + 1. **Start with the overview**: Understand the general structure and concepts.
2235 + 2. **Look for authentication details**: Figure out how to authenticate your requests.
2236 + 3. **Identify the endpoints you need**: Find specific functionality you want to use.
2237 + 4. **Check the request format**: Understand required and optional parameters.
2238 + 5. **Examine response examples**: Know what data to expect back.
2239 + 6. **Look for rate limits**: Understand usage restrictions.
2240 + 7. **Find error handling information**: Learn how to handle failures.
2241 +
2242 + ### API Documentation Example
2243 +
2244 + Here's how a typical API documentation entry might look:
2245 +
2246 + ```
2247 + GET /users/{user_id}
2248 +
2249 + Retrieves details for a specific user.
2250 +
2251 + Path Parameters:
2252 + - user_id (required): The ID of the user to retrieve
2253 +
2254 + Query Parameters:
2255 + - include_inactive (optional): Set to 'true' to include inactive users. Default: false
2256 + - fields (optional): Comma-separated list of fields to include in the response
2257 +
2258 + Request Headers:
2259 + - Authorization (required): Bearer {access_token}
2260 + - Accept (optional): application/json (default) or application/xml
2261 +
2262 + Response:
2263 + - 200 OK: User details retrieved successfully
2264 + - 404 Not Found: User does not exist
2265 + - 401 Unauthorized: Invalid or missing authentication
2266 +
2267 + Example Request:
2268 + GET /users/12345?fields=name,email HTTP/1.1
2269 + Host: api.example.com
2270 + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
2271 +
2272 + Example Response (200 OK):
2273 + {
2274 + "id": "12345",
2275 + "name": "John Doe",
2276 + "email": "john.doe@example.com"
2277 + }
2278 + ```
2279 +
2280 + ### Testing APIs
2281 +
2282 + #### Manual Testing with Tools
2283 +
2284 + Several tools can help you test APIs manually:
2285 +
2286 + 1. **Postman**: A graphical interface for building and testing HTTP requests
2287 + 2. **curl**: Command-line tool for making HTTP requests
2288 + 3. **httpie**: A more user-friendly command-line HTTP client
2289 +
2290 + **curl Example:**
2291 + ```bash
2292 + # Basic GET request
2293 + curl https://api.example.com/users
2294 +
2295 + # GET request with authentication
2296 + curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/users
2297 +
2298 + # POST request with JSON data
2299 + curl -X POST \
2300 + -H "Content-Type: application/json" \
2301 + -d '{"name": "John Doe", "email": "john@example.com"}' \
2302 + https://api.example.com/users
2303 + ```
2304 +
2305 + #### Automated API Testing
2306 +
2307 + Writing automated tests for API interactions ensures reliability:
2308 +
2309 + **Python with pytest:**
2310 + ```python
2311 + import pytest
2312 + import requests
2313 +
2314 + # API credentials
2315 + API_KEY = "your_api_key"
2316 + BASE_URL = "https://api.example.com"
2317 +
2318 + def get_auth_headers():
2319 + return {"Authorization": f"Bearer {API_KEY}"}
2320 +
2321 + def test_get_user():
2322 + """Test retrieving a user"""
2323 + user_id = "12345"
2324 + response = requests.get(f"{BASE_URL}/users/{user_id}", headers=get_auth_headers())
2325 +
2326 + # Check status code
2327 + assert response.status_code == 200
2328 +
2329 + # Check response structure
2330 + data = response.json()
2331 + assert "id" in data
2332 + assert "name" in data
2333 + assert "email" in data
2334 +
2335 + # Check specific data
2336 + assert data["id"] == user_id
2337 + assert "@" in data["email"] # Basic email validation
2338 +
2339 + def test_create_user():
2340 + """Test creating a user"""
2341 + new_user = {
2342 + "name": "Test User",
2343 + "email": "test@example.com",
2344 + "role": "user"
2345 + }
2346 +
2347 + response = requests.post(
2348 + f"{BASE_URL}/users",
2349 + headers={**get_auth_headers(), "Content-Type": "application/json"},
2350 + json=new_user
2351 + )
2352 +
2353 + # Check status code for successful creation
2354 + assert response.status_code == 201
2355 +
2356 + # Verify the created user has an ID
2357 + data = response.json()
2358 + assert "id" in data
2359 +
2360 + # Clean up - delete the test user
2361 + user_id = data["id"]
2362 + delete_response = requests.delete(f"{BASE_URL}/users/{user_id}", headers=get_auth_headers())
2363 + assert delete_response.status_code in [200, 204]
2364 + ```
2365 +
2366 + **Java with JUnit and RestAssured:**
2367 + ```java
2368 + import io.restassured.RestAssured;
2369 + import io.restassured.http.ContentType;
2370 + import org.junit.BeforeClass;
2371 + import org.junit.Test;
2372 + import static io.restassured.RestAssured.*;
2373 + import static org.hamcrest.Matchers.*;
2374 +
2375 + public class ApiTests {
2376 +
2377 + private static final String API_KEY = "your_api_key";
2378 +
2379 + @BeforeClass
2380 + public static void setup() {
2381 + RestAssured.baseURI = "https://api.example.com";
2382 + }
2383 +
2384 + @Test
2385 + public void testGetUser() {
2386 + String userId = "12345";
2387 +
2388 + given()
2389 + .header("Authorization", "Bearer " + API_KEY)
2390 + .when()
2391 + .get("/users/" + userId)
2392 + .then()
2393 + .statusCode(200)
2394 + .contentType(ContentType.JSON)
2395 + .body("id", equalTo(userId))
2396 + .body("name", notNullValue())
2397 + .body("email", containsString("@"));
2398 + }
2399 +
2400 + @Test
2401 + public void testCreateUser() {
2402 + String newUserId =
2403 + given()
2404 + .header("Authorization", "Bearer " + API_KEY)
2405 + .contentType(ContentType.JSON)
2406 + .body("{"
2407 + + "\"name\": \"Test User\","
2408 + + "\"email\": \"test@example.com\","
2409 + + "\"role\": \"user\""
2410 + + "}")
2411 + .when()
2412 + .post("/users")
2413 + .then()
2414 + .statusCode(201)
2415 + .contentType(ContentType.JSON)
2416 + .body("id", notNullValue())
2417 + .extract().path("id");
2418 +
2419 + // Clean up - delete the test user
2420 + given()
2421 + .header("Authorization", "Bearer " + API_KEY)
2422 + .when()
2423 + .delete("/users/" + newUserId)
2424 + .then()
2425 + .statusCode(anyOf(is(200), is(204)));
2426 + }
2427 + }
2428 + ```
2429 +
2430 + ### Creating Mock APIs for Testing
2431 +
2432 + When developing against an API that's not ready or when you want to test edge cases, mock APIs are useful:
2433 +
2434 + **Python with Flask:**
2435 + ```python
2436 + from flask import Flask, jsonify, request
2437 +
2438 + app = Flask(__name__)
2439 +
2440 + # In-memory database
2441 + users = {
2442 + "12345": {
2443 + "id": "12345",
2444 + "name": "John Doe",
2445 + "email": "john@example.com"
2446 + }
2447 + }
2448 +
2449 + @app.route('/users/<user_id>', methods=['GET'])
2450 + def get_user(user_id):
2451 + # Simulate authentication check
2452 + auth_header = request.headers.get('Authorization')
2453 + if not auth_header or not auth_header.startswith('Bearer '):
2454 + return jsonify({"error": "Unauthorized"}), 401
2455 +
2456 + # Check if user exists
2457 + if user_id not in users:
2458 + return jsonify({"error": "User not found"}), 404
2459 +
2460 + # Return user data
2461 + return jsonify(users[user_id])
2462 +
2463 + @app.route('/users', methods=['POST'])
2464 + def create_user():
2465 + # Simulate authentication check
2466 + auth_header = request.headers.get('Authorization')
2467 + if not auth_header or not auth_header.startswith('Bearer '):
2468 + return jsonify({"error": "Unauthorized"}), 401
2469 +
2470 + # Get request data
2471 + data = request.json
2472 +
2473 + # Validate required fields
2474 + if not data or 'name' not in data or 'email' not in data:
2475 + return jsonify({"error": "Missing required fields"}), 400
2476 +
2477 + # Create user ID (normally would be generated by database)
2478 + import uuid
2479 + user_id = str(uuid.uuid4())
2480 +
2481 + # Store user
2482 + users[user_id] = {
2483 + "id": user_id,
2484 + "name": data['name'],
2485 + "email": data['email'],
2486 + "role": data.get('role', 'user') # Default role
2487 + }
2488 +
2489 + return jsonify(users[user_id]), 201
2490 +
2491 + if __name__ == '__main__':
2492 + app.run(debug=True)
2493 + ```
2494 +
2495 + ### Documentation Tools
2496 +
2497 + Several tools can help you create and maintain API documentation:
2498 +
2499 + 1. **Swagger/OpenAPI**: Define your API structure in a standard format that can generate documentation, client libraries, and more.
2500 + 2. **Postman Documentation**: Create documentation directly from your Postman collections.
2501 + 3. **API Blueprint**: A markdown-based documentation format.
2502 + 4. **Docusaurus**: A documentation website generator popular for API docs.
2503 +
2504 + ### Practice Exercise
2505 +
2506 + 1. Find a public API with good documentation (GitHub, Stripe, Twilio, etc.) and study its structure.
2507 + 2. Use a tool like Postman or curl to make test requests to a public API.
2508 + 3. Write automated tests for basic CRUD operations against a public API or your mock API.
2509 + 4. Create a simple mock API for testing using Flask, Express.js, or another web framework.
2510 + 5. Document a small API you've created using OpenAPI/Swagger.
2511 +
2512 + ## 11. API Security Best Practices
2513 +
2514 + ### Common API Security Vulnerabilities
2515 +
2516 + APIs can be vulnerable to various security threats:
2517 +
2518 + 1. **Authentication Weaknesses**: Poor token management, weak password policies
2519 + 2. **Authorization Issues**: Missing permission checks, horizontal privilege escalation
2520 + 3. **Data Exposure**: Revealing sensitive data in responses
2521 + 4. **Injection Attacks**: SQL injection, command injection
2522 + 5. **Rate Limiting Bypass**: Allowing too many requests, leading to DoS
2523 + 6. **Man-in-the-Middle**: Intercepting unencrypted communications
2524 + 7. **Insecure Direct Object References**: Allowing access to unauthorized resources
2525 +
2526 + ### Security Implementation Best Practices
2527 +
2528 + #### 1. Always Use HTTPS
2529 +
2530 + Encrypt all API traffic using TLS:
2531 +
2532 + **Python:**
2533 + ```python
2534 + import requests
2535 +
2536 + # Always use HTTPS URLs
2537 + response = requests.get("https://api.example.com/data")
2538 +
2539 + # Verify SSL certificates (enabled by default in requests)
2540 + response = requests.get("https://api.example.com/data", verify=True)
2541 +
2542 + # You can also specify a certificate bundle
2543 + response = requests.get("https://api.example.com/data", verify="/path/to/certfile")
2544 + ```
2545 +
2546 + **Java:**
2547 + ```java
2548 + import javax.net.ssl.HttpsURLConnection;
2549 + import java.net.URL;
2550 +
2551 + URL url = new URL("https://api.example.com/data");
2552 + HttpsURLConnection connection = (HttpsURLConnection) url.openConnection();
2553 +
2554 + // Enable hostname verification (default is true)
2555 + connection.setHostnameVerifier(HttpsURLConnection.getDefaultHostnameVerifier());
2556 + ```
2557 +
2558 + #### 2. Implement Proper Authentication
2559 +
2560 + Use secure authentication methods:
2561 +
2562 + **OAuth 2.0 Flow in Python:**
2563 + ```python
2564 + import requests
2565 +
2566 + # Step 1: Authorization Request (redirect user to this URL)
2567 + auth_url = "https://auth.example.com/oauth/authorize"
2568 + auth_params = {
2569 + "response_type": "code",
2570 + "client_id": "YOUR_CLIENT_ID",
2571 + "redirect_uri": "YOUR_REDIRECT_URI",
2572 + "scope": "read write",
2573 + "state": "RANDOM_STATE_STRING" # Prevent CSRF
2574 + }
2575 +
2576 + # After user authorizes, they are redirected to your redirect_uri with a code
2577 +
2578 + # Step 2: Exchange code for token
2579 + token_url = "https://auth.example.com/oauth/token"
2580 + token_params = {
2581 + "grant_type": "authorization_code",
2582 + "code": "AUTH_CODE_FROM_REDIRECT",
2583 + "redirect_uri": "YOUR_REDIRECT_URI",
2584 + "client_id": "YOUR_CLIENT_ID",
2585 + "client_secret": "YOUR_CLIENT_SECRET"
2586 + }
2587 +
2588 + token_response = requests.post(token_url, data=token_params)
2589 + tokens = token_response.json()
2590 + access_token = tokens["access_token"]
2591 +
2592 + # Step 3: Use token in API requests
2593 + headers = {"Authorization": f"Bearer {access_token}"}
2594 + api_response = requests.get("https://api.example.com/data", headers=headers)
2595 + ```
2596 +
2597 + #### 3. Secure Storage of Credentials
2598 +
2599 + Never hardcode or expose credentials:
2600 +
2601 + **Python:**
2602 + ```python
2603 + import os
2604 + from dotenv import load_dotenv
2605 +
2606 + # Load credentials from environment variables
2607 + load_dotenv() # Load variables from .env file
2608 +
2609 + api_key = os.environ.get("API_KEY")
2610 + client_secret = os.environ.get("CLIENT_SECRET")
2611 +
2612 + # Use credentials in requests
2613 + headers = {"Authorization": f"Bearer {api_key}"}
2614 + ```
2615 +
2616 + **Java:**
2617 + ```java
2618 + // Load from environment variables
2619 + String apiKey = System.getenv("API_KEY");
2620 + String clientSecret = System.getenv("CLIENT_SECRET");
2621 +
2622 + // Or from properties file (not included in version control)
2623 + Properties prop = new Properties();
2624 + try (FileInputStream input = new FileInputStream("config.properties")) {
2625 + prop.load(input);
2626 + }
2627 + String apiKey = prop.getProperty("api.key");
2628 + ```
2629 +
2630 + #### 4. Input Validation
2631 +
2632 + Always validate and sanitize input:
2633 +
2634 + **Python:**
2635 + ```python
2636 + def validate_user_input(user_data):
2637 + errors = {}
2638 +
2639 + # Check required fields
2640 + if "email" not in user_data or not user_data["email"]:
2641 + errors["email"] = "Email is required"
2642 + elif not re.match(r"[^@]+@[^@]+\.[^@]+", user_data["email"]):
2643 + errors["email"] = "Invalid email format"
2644 +
2645 + # Validate numeric values
2646 + if "age" in user_data:
2647 + try:
2648 + age = int(user_data["age"])
2649 + if age < 0 or age > 120:
2650 + errors["age"] = "Age must be between 0 and 120"
2651 + except ValueError:
2652 + errors["age"] = "Age must be a number"
2653 +
2654 + # Sanitize text fields
2655 + if "name" in user_data:
2656 + # Remove any HTML tags
2657 + user_data["name"] = re.sub(r"<[^>]*>", "", user_data["name"])
2658 +
2659 + return errors, user_data
2660 + ```
2661 +
2662 + #### 5. Protect Against Common Attacks
2663 +
2664 + Guard against injection and other attacks:
2665 +
2666 + **SQL Injection Prevention (Python with SQLAlchemy):**
2667 + ```python
2668 + from sqlalchemy import create_engine, text
2669 + from sqlalchemy.orm import sessionmaker
2670 +
2671 + engine = create_engine("postgresql://user:pass@localhost/dbname")
2672 + Session = sessionmaker(bind=engine)
2673 + session = Session()
2674 +
2675 + # UNSAFE:
2676 + # user_id = request.args.get("user_id")
2677 + # query = f"SELECT * FROM users WHERE id = {user_id}" # VULNERABLE!
2678 + # result = session.execute(query)
2679 +
2680 + # SAFE:
2681 + user_id = request.args.get("user_id")
2682 + # Use parameterized queries
2683 + result = session.execute(
2684 + text("SELECT * FROM users WHERE id = :user_id"),
2685 + {"user_id": user_id}
2686 + )
2687 + ```
2688 +
2689 + **XSS Prevention:**
2690 + ```python
2691 + import html
2692 +
2693 + def render_user_content(content):
2694 + # Escape HTML special characters
2695 + safe_content = html.escape(content)
2696 + return safe_content
2697 + ```
2698 +
2699 + #### 6. Implement Proper Logging
2700 +
2701 + Log security events without exposing sensitive data:
2702 +
2703 + **Python:**
2704 + ```python
2705 + import logging
2706 + import re
2707 +
2708 + # Configure logging
2709 + logging.basicConfig(
2710 + filename="api_security.log",
2711 + level=logging.INFO,
2712 + format="%(asctime)s - %(levelname)s - %(message)s"
2713 + )
2714 +
2715 + def log_api_request(request, user_id=None):
2716 + # Mask sensitive data
2717 + headers = request.headers.copy()
2718 + if "Authorization" in headers:
2719 + headers["Authorization"] = "Bearer [REDACTED]"
2720 +
2721 + # Log request details
2722 + logging.info({
2723 + "method": request.method,
2724 + "path": request.path,
2725 + "user_id": user_id,
2726 + "ip": request.remote_addr,
2727 + "user_agent": request.user_agent.string,
2728 + "headers": headers
2729 + })
2730 +
2731 + def log_authentication_failure(username, ip, reason):
2732 + logging.warning(f"Auth failure: {reason}, User: {mask_pii(username)}, IP: {ip}")
2733 +
2734 + def mask_pii(text):
2735 + """Mask personally identifiable information"""
2736 + # Mask email addresses
2737 + text = re.sub(r"([a-zA-Z0-9._%+-]+)@([a-zA-Z0-9.-]+\.[a-zA-Z]{2,})", r"***@\2", text)
2738 +
2739 + # Mask credit card numbers
2740 + text = re.sub(r"\b(\d{4})\d{8,12}(\d{4})\b", r"\1********\2", text)
2741 +
2742 + return text
2743 + ```
2744 +
2745 + ### Practice Exercise
2746 +
2747 + 1. Audit an existing API client for security vulnerabilities:
2748 + - Check for hardcoded credentials
2749 + - Verify HTTPS usage
2750 + - Look for proper input validation
2751 + - Check token handling
2752 + 2. Implement secure credential storage using environment variables or a secure configuration system.
2753 + 3. Create a function to validate and sanitize API inputs before sending them.
2754 + 4. Implement proper token handling with secure storage and automatic refresh for expired tokens.
2755 + 5. Write a logging system that captures security events without exposing sensitive data.
2756 +
2757 + ## 12. Real-World API Integration Examples
2758 +
2759 + Let's look at some real-world examples of integrating with popular APIs:
2760 +
2761 + ### Example 1: Weather Forecast Application
2762 +
2763 + **Requirements:**
2764 + - Display current weather and 5-day forecast for a location
2765 + - Show temperature, humidity, wind speed, and conditions
2766 + - Allow searching by city name or coordinates
2767 +
2768 + **API Choice:** OpenWeatherMap API
2769 +
2770 + **Implementation in Python:**
2771 +
2772 + ```python
2773 + import requests
2774 + import os
2775 + from datetime import datetime
2776 +
2777 + class WeatherApp:
2778 + def __init__(self, api_key=None):
2779 + self.api_key = api_key or os.environ.get("OPENWEATHERMAP_API_KEY")
2780 + self.base_url = "https://api.openweathermap.org/data/2.5"
2781 +
2782 + def get_current_weather(self, city=None, lat=None, lon=None):
2783 + """Get current weather for a location"""
2784 + # Prepare parameters
2785 + params = {
2786 + "appid": self.api_key,
2787 + "units": "metric" # Use metric units (Celsius)
2788 + }
2789 +
2790 + # Set location parameter
2791 + if city:
2792 + params["q"] = city
2793 + elif lat is not None and lon is not None:
2794 + params["lat"] = lat
2795 + params["lon"] = lon
2796 + else:
2797 + raise ValueError("Either city name or coordinates must be provided")
2798 +
2799 + # Make request
2800 + response = requests.get(f"{self.base_url}/weather", params=params)
2801 +
2802 + # Check for errors
2803 + if response.status_code != 200:
2804 + return self._handle_error(response)
2805 +
2806 + # Parse and format response
2807 + data = response.json()
2808 + return {
2809 + "location": data["name"],
2810 + "country": data["sys"]["country"],
2811 + "temperature": round(data["main"]["temp"]),
2812 + "feels_like": round(data["main"]["feels_like"]),
2813 + "humidity": data["main"]["humidity"],
2814 + "wind_speed": data["wind"]["speed"],
2815 + "conditions": data["weather"][0]["description"],
2816 + "icon": data["weather"][0]["icon"],
2817 + "timestamp": datetime.fromtimestamp(data["dt"]).strftime("%Y-%m-%d %H:%M:%S")
2818 + }
2819 +
2820 + def get_forecast(self, city=None, lat=None, lon=None):
2821 + """Get 5-day forecast for a location"""
2822 + # Prepare parameters
2823 + params = {
2824 + "appid": self.api_key,
2825 + "units": "metric"
2826 + }
2827 +
2828 + # Set location parameter
2829 + if city:
2830 + params["q"] = city
2831 + elif lat is not None and lon is not None:
2832 + params["lat"] = lat
2833 + params["lon"] = lon
2834 + else:
2835 + raise ValueError("Either city name or coordinates must be provided")
2836 +
2837 + # Make request
2838 + response = requests.get(f"{self.base_url}/forecast", params=params)
2839 +
2840 + # Check for errors
2841 + if response.status_code != 200:
2842 + return self._handle_error(response)
2843 +
2844 + # Parse and format response
2845 + data = response.json()
2846 + forecasts = []
2847 +
2848 + # Group forecasts by day (OpenWeatherMap returns 3-hour intervals)
2849 + days = {}
2850 + for item in data["list"]:
2851 + # Get date (without time)
2852 + date = datetime.fromtimestamp(item["dt"]).strftime("%Y-%m-%d")
2853 +
2854 + if date not in days:
2855 + days[date] = []
2856 +
2857 + days[date].append({
2858 + "timestamp": item["dt"],
2859 + "temperature": round(item["main"]["temp"]),
2860 + "conditions": item["weather"][0]["description"],
2861 + "icon": item["weather"][0]["icon"],
2862 + "wind_speed": item["wind"]["speed"],
2863 + "humidity": item["main"]["humidity"]
2864 + })
2865 +
2866 + # Format each day's forecast (using midday forecast as representative)
2867 + for date, items in days.items():
2868 + # Get the forecast closest to midday
2869 + midday_forecast = min(items, key=lambda x: abs(
2870 + datetime.fromtimestamp(x["timestamp"]).hour - 12
2871 + ))
2872 +
2873 + # Format the day's forecast
2874 + readable_date = datetime.strptime(date, "%Y-%m-%d").strftime("%A, %b %d")
2875 + forecasts.append({
2876 + "date": readable_date,
2877 + "temperature": midday_forecast["temperature"],
2878 + "conditions": midday_forecast["conditions"],
2879 + "icon": midday_forecast["icon"],
2880 + "wind_speed": midday_forecast["wind_speed"],
2881 + "humidity": midday_forecast["humidity"]
2882 + })
2883 +
2884 + return {
2885 + "location": data["city"]["name"],
2886 + "country": data["city"]["country"],
2887 + "forecasts": forecasts[:5] # Limit to 5 days
2888 + }
2889 +
2890 + def _handle_error(self, response):
2891 + """Handle API error responses"""
2892 + try:
2893 + error_data = response.json()
2894 + error_message = error_data.get("message", "Unknown error")
2895 + except:
2896 + error_message = f"Error: HTTP {response.status_code}"
2897 +
2898 + return {
2899 + "error": True,
2900 + "message": error_message,
2901 + "status_code": response.status_code
2902 + }
2903 +
2904 + # Example usage
2905 + if __name__ == "__main__":
2906 + weather_app = WeatherApp()
2907 +
2908 + # Get current weather
2909 + current = weather_app.get_current_weather(city="London")
2910 + if "error" not in current:
2911 + print(f"Current weather in {current['location']}:")
2912 + print(f"Temperature: {current['temperature']}°C")
2913 + print(f"Conditions: {current['conditions']}")
2914 + print(f"Wind Speed: {current['wind_speed']} m/s")
2915 + print(f"Humidity: {current['humidity']}%")
2916 + else:
2917 + print(f"Error: {current['message']}")
2918 +
2919 + # Get forecast
2920 + forecast = weather_app.get_forecast(city="London")
2921 + if "error" not in forecast:
2922 + print(f"\n5-day forecast for {forecast['location']}:")
2923 + for day in forecast["forecasts"]:
2924 + print(f"{day['date']}: {day['temperature']}°C, {day['conditions']}")
2925 + ```
2926 +
2927 + ### Example 2: GitHub Repository Browser
2928 +
2929 + **Requirements:**
2930 + - List a user's repositories
2931 + - Show repository details (stars, forks, language)
2932 + - Display recent commits
2933 +
2934 + **API Choice:** GitHub REST API
2935 +
2936 + **Implementation in Java:**
2937 +
2938 + ```java
2939 + import java.io.BufferedReader;
2940 + import java.io.IOException;
2941 + import java.io.InputStreamReader;
2942 + import java.net.HttpURLConnection;
2943 + import java.net.URL;
2944 + import java.text.SimpleDateFormat;
2945 + import java.util.ArrayList;
2946 + import java.util.Date;
2947 + import java.util.List;
2948 + import org.json.JSONArray;
2949 + import org.json.JSONObject;
2950 +
2951 + public class GitHubApp {
2952 + private final String apiToken;
2953 + private final String baseUrl = "https://api.github.com";
2954 +
2955 + public GitHubApp(String apiToken) {
2956 + this.apiToken = apiToken;
2957 + }
2958 +
2959 + public List<Repository> getUserRepositories(String username) throws IOException {
2960 + String endpoint = "/users/" + username + "/repos";
2961 + JSONArray reposJson = makeRequest(endpoint);
2962 +
2963 + List<Repository> repositories = new ArrayList<>();
2964 + for (int i = 0; i < reposJson.length(); i++) {
2965 + JSONObject repoJson = reposJson.getJSONObject(i);
2966 +
2967 + Repository repo = new Repository();
2968 + repo.id = repoJson.getInt("id");
2969 + repo.name = repoJson.getString("name");
2970 + repo.fullName = repoJson.getString("full_name");
2971 + repo.description = repoJson.isNull("description") ? "" : repoJson.getString("description");
2972 + repo.url = repoJson.getString("html_url");
2973 + repo.stars = repoJson.getInt("stargazers_count");
2974 + repo.forks = repoJson.getInt("forks_count");
2975 + repo.language = repoJson.isNull("language") ? "Unknown" : repoJson.getString("language");
2976 + repo.createdAt = parseDate(repoJson.getString("created_at"));
2977 +
2978 + repositories.add(repo);
2979 + }
2980 +
2981 + return repositories;
2982 + }
2983 +
2984 + public List<Commit> getRepositoryCommits(String owner, String repo, int limit) throws IOException {
2985 + String endpoint = "/repos/" + owner + "/" + repo + "/commits";
2986 + JSONArray commitsJson = makeRequest(endpoint);
2987 +
2988 + List<Commit> commits = new ArrayList<>();
2989 + int count = Math.min(commitsJson.length(), limit);
2990 +
2991 + for (int i = 0; i < count; i++) {
2992 + JSONObject commitJson = commitsJson.getJSONObject(i);
2993 +
2994 + Commit commit = new Commit();
2995 + commit.sha = commitJson.getString("sha");
2996 +
2997 + JSONObject commitDetails = commitJson.getJSONObject("commit");
2998 + commit.message = commitDetails.getString("message");
2999 +
3000 + JSONObject authorJson = commitDetails.getJSONObject("author");
3001 + commit.authorName = authorJson.getString("name");
3002 + commit.authorEmail = authorJson.getString("email");
3003 + commit.date = parseDate(authorJson.getString("date"));
3004 +
3005 + commits.add(commit);
3006 + }
3007 +
3008 + return commits;
3009 + }
3010 +
3011 + private JSONArray makeRequest(String endpoint) throws IOException {
3012 + URL url = new URL(baseUrl + endpoint);
3013 + HttpURLConnection connection = (HttpURLConnection) url.openConnection();
3014 +
3015 + // Set headers
3016 + connection.setRequestProperty("Accept", "application/vnd.github.v3+json");
3017 + if (apiToken != null && !apiToken.isEmpty()) {
3018 + connection.setRequestProperty("Authorization", "token " + apiToken);
3019 + }
3020 +
3021 + // Check response code
3022 + int responseCode = connection.getResponseCode();
3023 + if (responseCode != 200) {
3024 + throw new IOException("API request failed with status: " + responseCode);
3025 + }
3026 +
3027 + // Read response
3028 + BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
3029 + StringBuilder response = new StringBuilder();
3030 + String line;
3031 +
3032 + while ((line = reader.readLine()) != null) {
3033 + response.append(line);
3034 + }
3035 + reader.close();
3036 +
3037 + // Parse JSON response
3038 + return new JSONArray(response.toString());
3039 + }
3040 +
3041 + private Date parseDate(String dateString) {
3042 + try {
3043 + SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
3044 + return formatter.parse(dateString);
3045 + } catch (Exception e) {
3046 + return new Date(); // Return current date as fallback
3047 + }
3048 + }
3049 +
3050 + // Data models
3051 + public static class Repository {
3052 + public int id;
3053 + public String name;
3054 + public String fullName;
3055 + public String description;
3056 + public String url;
3057 + public int stars;
3058 + public int forks;
3059 + public String language;
3060 + public Date createdAt;
3061 +
3062 + @Override
3063 + public String toString() {
3064 + SimpleDateFormat dateFormat = new SimpleDateFormat("MMM dd, yyyy");
3065 + return String.format("%s - %d★ %d🍴 (%s) - Created on %s",
3066 + fullName, stars, forks, language, dateFormat.format(createdAt));
3067 + }
3068 + }
3069 +
3070 + public static class Commit {
3071 + public String sha;
3072 + public String message;
3073 + public String authorName;
3074 + public String authorEmail;
3075 + public Date date;
3076 +
3077 + @Override
3078 + public String toString() {
3079 + SimpleDateFormat dateFormat = new SimpleDateFormat("MMM dd, yyyy HH:mm");
3080 + return String.format("[%s] %s <%s> - %s",
3081 + dateFormat.format(date), authorName, authorEmail, message);
3082 + }
3083 + }
3084 +
3085 + // Example usage
3086 + public static void main(String[] args) {
3087 + try {
3088 + String token = System.getenv("GITHUB_TOKEN"); // Get from environment variable
3089 + GitHubApp app = new GitHubApp(token);
3090 +
3091 + // Get repositories for a user
3092 + String username = "octocat";
3093 + List<Repository> repos = app.getUserRepositories(username);
3094 +
3095 + System.out.println("Repositories for " + username + ":");
3096 + for (Repository repo : repos) {
3097 + System.out.println(repo);
3098 + }
3099 +
3100 + // Get commits for a repository
3101 + if (!repos.isEmpty()) {
3102 + Repository firstRepo = repos.get(0);
3103 + String[] parts = firstRepo.fullName.split("/");
3104 + List<Commit> commits = app.getRepositoryCommits(parts[0], parts[1], 5);
3105 +
3106 + System.out.println("\nRecent commits for " + firstRepo.fullName + ":");
3107 + for (Commit commit : commits) {
3108 + System.out.println(commit);
3109 + }
3110 + }
3111 +
3112 + } catch (IOException e) {
3113 + System.err.println("Error: " + e.getMessage());
3114 + }
3115 + }
3116 + }
3117 + ```
3118 +
3119 + ### Example 3: E-commerce Product Inventory System
3120 +
3121 + **Requirements:**
3122 + - Retrieve product catalog from an API
3123 + - Add, update, and remove products
3124 + - Handle product categories and attributes
3125 +
3126 + **API Choice:** Custom REST API
3127 +
3128 + **Implementation in Python:**
3129 +
3130 + ```python
3131 + import requests
3132 + import json
3133 + import logging
3134 + import time
3135 + import os
3136 + from typing import Dict, List, Optional, Any, Union
3137 +
3138 + # Set up logging
3139 + logging.basicConfig(
3140 + level=logging.INFO,
3141 + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
3142 + filename='product_api.log'
3143 + )
3144 + logger = logging.getLogger('product_api')
3145 +
3146 + class ProductAPI:
3147 + def __init__(self, api_url: str, api_key: str = None):
3148 + """Initialize the Product API client"""
3149 + self.api_url = api_url.rstrip('/')
3150 + self.api_key = api_key or os.environ.get('PRODUCT_API_KEY')
3151 + self.session = requests.Session()
3152 +
3153 + # Set default headers
3154 + self.session.headers.update({
3155 + 'Content-Type': 'application/json',
3156 + 'Accept': 'application/json',
3157 + 'X-API-Key': self.api_key
3158 + })
3159 +
3160 + def get_products(self, category: str = None, page: int = 1,
3161 + limit: int = 50, sort_by: str = 'name') -> Dict:
3162 + """Get list of products with optional filtering"""
3163 + endpoint = '/products'
3164 + params = {
3165 + 'page': page,
3166 + 'limit': limit,
3167 + 'sort': sort_by
3168 + }
3169 +
3170 + if category:
3171 + params['category'] = category
3172 +
3173 + return self._make_request('GET', endpoint, params=params)
3174 +
3175 + def get_product(self, product_id: str) -> Dict:
3176 + """Get details for a specific product"""
3177 + endpoint = f'/products/{product_id}'
3178 + return self._make_request('GET', endpoint)
3179 +
3180 + def create_product(self, product_data: Dict) -> Dict:
3181 + """Create a new product"""
3182 + self._validate_product_data(product_data, is_new=True)
3183 + endpoint = '/products'
3184 + return self._make_request('POST', endpoint, json=product_data)
3185 +
3186 + def update_product(self, product_id: str, product_data: Dict) -> Dict:
3187 + """Update an existing product"""
3188 + self._validate_product_data(product_data, is_new=False)
3189 + endpoint = f'/products/{product_id}'
3190 + return self._make_request('PUT', endpoint, json=product_data)
3191 +
3192 + def delete_product(self, product_id: str) -> Dict:
3193 + """Delete a product"""
3194 + endpoint = f'/products/{product_id}'
3195 + return self._make_request('DELETE', endpoint)
3196 +
3197 + def get_categories(self) -> List[Dict]:
3198 + """Get list of product categories"""
3199 + endpoint = '/categories'
3200 + return self._make_request('GET', endpoint)
3201 +
3202 + def search_products(self, query: str, category: str = None,
3203 + page: int = 1, limit: int = 20) -> Dict:
3204 + """Search for products"""
3205 + endpoint = '/products/search'
3206 + params = {
3207 + 'q': query,
3208 + 'page': page,
3209 + 'limit': limit
3210 + }
3211 +
3212 + if category:
3213 + params['category'] = category
3214 +
3215 + return self._make_request('GET', endpoint, params=params)
3216 +
3217 + def bulk_update_prices(self, price_updates: List[Dict]) -> Dict:
3218 + """Update prices for multiple products at once"""
3219 + endpoint = '/products/price-update'
3220 + return self._make_request('POST', endpoint, json={'updates': price_updates})
3221 +
3222 + def _validate_product_data(self, data: Dict, is_new: bool = False) -> None:
3223 + """Validate product data before sending to API"""
3224 + required_fields = ['name', 'price', 'category_id', 'description', 'sku']
3225 +
3226 + if is_new: # Only check required fields for new products
3227 + missing = [field for field in required_fields if field not in data]
3228 + if missing:
3229 + raise ValueError(f"Missing required fields: {', '.join(missing)}")
3230 +
3231 + # Validate price format
3232 + if 'price' in data and not isinstance(data['price'], (int, float)):
3233 + raise ValueError("Price must be a number")
3234 +
3235 + # Validate SKU format if present
3236 + if 'sku' in data and not isinstance(data['sku'], str):
3237 + raise ValueError("SKU must be a string")
3238 +
3239 + def _make_request(self, method: str, endpoint: str,
3240 + params: Dict = None, json: Dict = None,
3241 + retry_count: int = 3) -> Union[Dict, List]:
3242 + """Make HTTP request to the API with retry logic"""
3243 + url = f"{self.api_url}{endpoint}"
3244 + logger.info(f"Making {method} request to {url}")
3245 +
3246 + for attempt in range(retry_count):
3247 + try:
3248 + response = self.session.request(
3249 + method=method,
3250 + url=url,
3251 + params=params,
3252 + json=json,
3253 + timeout=10
3254 + )
3255 +
3256 + # Log response status
3257 + logger.info(f"Response status: {response.status_code}")
3258 +
3259 + # Handle different status codes
3260 + if 200 <= response.status_code < 300:
3261 + return response.json()
3262 +
3263 + elif response.status_code == 429: # Rate limited
3264 + retry_after = int(response.headers.get('Retry-After', 5))
3265 + logger.warning(f"Rate limited. Waiting {retry_after} seconds.")
3266 + time.sleep(retry_after)
3267 + continue
3268 +
3269 + elif response.status_code == 401:
3270 + logger.error("Authentication failed. Check your API key.")
3271 + raise AuthenticationError("Invalid API key")
3272 +
3273 + elif response.status_code == 404:
3274 + logger.error(f"Resource not found: {url}")
3275 + raise ResourceNotFoundError(f"Resource not found: {endpoint}")
3276 +
3277 + elif response.status_code >= 500:
3278 + # Server error, retry with backoff
3279 + wait_time = (2 ** attempt) + 1
3280 + logger.warning(f"Server error {response.status_code}. Retrying in {wait_time}s.")
3281 + time.sleep(wait_time)
3282 + continue
3283 +
3284 + else:
3285 + # Try to get error details from response
3286 + try:
3287 + error_data = response.json()
3288 + error_message = error_data.get("message", f"API error: {response.status_code}")
3289 + except:
3290 + error_message = f"API error: {response.status_code}"
3291 +
3292 + logger.error(error_message)
3293 + raise APIError(error_message, response.status_code)
3294 +
3295 + except requests.exceptions.RequestException as e:
3296 + # Network error, retry with backoff if attempts remain
3297 + if attempt < retry_count - 1:
3298 + wait_time = (2 ** attempt) + 1
3299 + logger.warning(f"Request failed: {e}. Retrying in {wait_time}s.")
3300 + time.sleep(wait_time)
3301 + else:
3302 + logger.error(f"Request failed after {retry_count} attempts: {e}")
3303 + raise ConnectionError(f"Failed to connect to API: {e}")
3304 +
3305 + # This should never be reached due to the exceptions above
3306 + return None
3307 +
3308 + # Custom exception classes
3309 + class AuthenticationError(Exception):
3310 + """Raised when authentication fails"""
3311 + pass
3312 +
3313 + class ResourceNotFoundError(Exception):
3314 + """Raised when a requested resource doesn't exist"""
3315 + pass
3316 +
3317 + class APIError(Exception):
3318 + """Generic API error"""
3319 + def __init__(self, message, status_code=None):
3320 + self.status_code = status_code
3321 + super().__init__(message)
3322 +
3323 + # Example usage
3324 + if __name__ == "__main__":
3325 + # Initialize API client
3326 + api = ProductAPI(
3327 + api_url="https://api.example.com/v1",
3328 + api_key="your_api_key_here" # Better to use environment variable
3329 + )
3330 +
3331 + try:
3332 + # Get all products
3333 + products = api.get_products(limit=10)
3334 + print(f"Found {len(products['data'])} products:")
3335 + for product in products['data']:
3336 + print(f"{product['name']} - ${product['price']} - SKU: {product['sku']}")
3337 +
3338 + # Search for products
3339 + search_results = api.search_products("smartphone")
3340 + print(f"\nSearch results for 'smartphone': {len(search_results['data'])} products found")
3341 +
3342 + # Create a new product
3343 + new_product = {
3344 + "name": "Wireless Headphones",
3345 + "description": "Premium wireless headphones with noise cancellation",
3346 + "price": 129.99,
3347 + "sku": "WHEAD-101",
3348 + "category_id": "electronics",
3349 + "stock": 45,
3350 + "attributes": {
3351 + "color": "black",
3352 + "bluetooth_version": "5.0",
3353 + "battery_life": "20 hours"
3354 + }
3355 + }
3356 +
3357 + result = api.create_product(new_product)
3358 + print(f"\nCreated new product: {result['name']} (ID: {result['id']})")
3359 +
3360 + # Update the product
3361 + update_data = {
3362 + "price": 119.99,
3363 + "stock": 50,
3364 + "attributes": {
3365 + "on_sale": True,
3366 + "discount_reason": "Summer Sale"
3367 + }
3368 + }
3369 +
3370 + updated = api.update_product(result['id'], update_data)
3371 + print(f"\nUpdated product price to ${updated['price']}")
3372 +
3373 + # Get categories
3374 + categories = api.get_categories()
3375 + print("\nAvailable categories:")
3376 + for category in categories:
3377 + print(f"- {category['name']} ({category['id']})")
3378 +
3379 + except AuthenticationError as e:
3380 + print(f"Authentication error: {e}")
3381 + except ResourceNotFoundError as e:
3382 + print(f"Not found: {e}")
3383 + except APIError as e:
3384 + print(f"API error ({e.status_code}): {e}")
3385 + except ConnectionError as e:
3386 + print(f"Connection error: {e}")
3387 + except ValueError as e:
3388 + print(f"Validation error: {e}")
3389 + ```
3390 +
3391 + ### Example 4: Payment Processing Integration
3392 +
3393 + **Requirements:**
3394 + - Process credit card payments
3395 + - Handle different payment methods
3396 + - Support refunds and payment status checks
3397 +
3398 + **API Choice:** Stripe API
3399 +
3400 + **Implementation in JavaScript (Node.js):**
3401 +
3402 + ```javascript
3403 + // payment-service.js
3404 + const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
3405 + const logger = require('./logger');
3406 +
3407 + class PaymentService {
3408 + constructor(apiKey = process.env.STRIPE_SECRET_KEY) {
3409 + this.stripe = require('stripe')(apiKey);
3410 + }
3411 +
3412 + /**
3413 + * Create a payment intent for a credit card payment
3414 + */
3415 + async createPaymentIntent(amount, currency, customerId, description) {
3416 + try {
3417 + logger.info(`Creating payment intent for ${currency} ${amount / 100}`);
3418 +
3419 + const paymentIntent = await this.stripe.paymentIntents.create({
3420 + amount: amount, // amount in cents
3421 + currency: currency,
3422 + customer: customerId,
3423 + description: description,
3424 + payment_method_types: ['card'],
3425 + capture_method: 'automatic'
3426 + });
3427 +
3428 + logger.info(`Created payment intent: ${paymentIntent.id}`);
3429 + return {
3430 + success: true,
3431 + paymentIntentId: paymentIntent.id,
3432 + clientSecret: paymentIntent.client_secret,
3433 + status: paymentIntent.status
3434 + };
3435 + } catch (error) {
3436 + logger.error(`Error creating payment intent: ${error.message}`);
3437 + return {
3438 + success: false,
3439 + error: error.message,
3440 + code: error.code
3441 + };
3442 + }
3443 + }
3444 +
3445 + /**
3446 + * Create a customer in Stripe
3447 + */
3448 + async createCustomer(email, name, metadata = {}) {
3449 + try {
3450 + logger.info(`Creating customer for email: ${email}`);
3451 +
3452 + const customer = await this.stripe.customers.create({
3453 + email: email,
3454 + name: name,
3455 + metadata: metadata
3456 + });
3457 +
3458 + logger.info(`Created customer: ${customer.id}`);
3459 + return {
3460 + success: true,
3461 + customerId: customer.id,
3462 + email: customer.email
3463 + };
3464 + } catch (error) {
3465 + logger.error(`Error creating customer: ${error.message}`);
3466 + return {
3467 + success: false,
3468 + error: error.message,
3469 + code: error.code
3470 + };
3471 + }
3472 + }
3473 +
3474 + /**
3475 + * Add a payment method to a customer
3476 + */
3477 + async attachPaymentMethodToCustomer(customerId, paymentMethodId) {
3478 + try {
3479 + logger.info(`Attaching payment method ${paymentMethodId} to customer ${customerId}`);
3480 +
3481 + await this.stripe.paymentMethods.attach(paymentMethodId, {
3482 + customer: customerId,
3483 + });
3484 +
3485 + // Set as default payment method
3486 + await this.stripe.customers.update(customerId, {
3487 + invoice_settings: {
3488 + default_payment_method: paymentMethodId,
3489 + },
3490 + });
3491 +
3492 + logger.info(`Payment method attached and set as default`);
3493 + return {
3494 + success: true,
3495 + customerId: customerId,
3496 + paymentMethodId: paymentMethodId
3497 + };
3498 + } catch (error) {
3499 + logger.error(`Error attaching payment method: ${error.message}`);
3500 + return {
3501 + success: false,
3502 + error: error.message,
3503 + code: error.code
3504 + };
3505 + }
3506 + }
3507 +
3508 + /**
3509 + * Process a payment with an existing payment method
3510 + */
3511 + async processPayment(amount, currency, customerId, paymentMethodId, description) {
3512 + try {
3513 + logger.info(`Processing payment of ${currency} ${amount / 100} with payment method ${paymentMethodId}`);
3514 +
3515 + const paymentIntent = await this.stripe.paymentIntents.create({
3516 + amount: amount,
3517 + currency: currency,
3518 + customer: customerId,
3519 + payment_method: paymentMethodId,
3520 + description: description,
3521 + confirm: true, // Confirm the payment intent immediately
3522 + off_session: true // Customer is not present
3523 + });
3524 +
3525 + logger.info(`Payment processed: ${paymentIntent.id} (${paymentIntent.status})`);
3526 + return {
3527 + success: true,
3528 + paymentIntentId: paymentIntent.id,
3529 + status: paymentIntent.status
3530 + };
3531 + } catch (error) {
3532 + logger.error(`Error processing payment: ${error.message}`);
3533 +
3534 + // Check if payment requires authentication
3535 + if (error.code === 'authentication_required') {
3536 + return {
3537 + success: false,
3538 + requiresAuthentication: true,
3539 + paymentIntentId: error.raw.payment_intent.id,
3540 + clientSecret: error.raw.payment_intent.client_secret,
3541 + error: "This payment requires authentication"
3542 + };
3543 + }
3544 +
3545 + return {
3546 + success: false,
3547 + error: error.message,
3548 + code: error.code
3549 + };
3550 + }
3551 + }
3552 +
3553 + /**
3554 + * Issue a refund for a payment
3555 + */
3556 + async refundPayment(paymentIntentId, amount = null, reason = 'requested_by_customer') {
3557 + try {
3558 + logger.info(`Refunding payment ${paymentIntentId}`);
3559 +
3560 + const refundParams = {
3561 + payment_intent: paymentIntentId,
3562 + reason: reason
3563 + };
3564 +
3565 + // If amount is specified, add it to refund only that amount
3566 + if (amount !== null) {
3567 + refundParams.amount = amount;
3568 + }
3569 +
3570 + const refund = await this.stripe.refunds.create(refundParams);
3571 +
3572 + logger.info(`Refund issued: ${refund.id}`);
3573 + return {
3574 + success: true,
3575 + refundId: refund.id,
3576 + status: refund.status
3577 + };
3578 + } catch (error) {
3579 + logger.error(`Error refunding payment: ${error.message}`);
3580 + return {
3581 + success: false,
3582 + error: error.message,
3583 + code: error.code
3584 + };
3585 + }
3586 + }
3587 +
3588 + /**
3589 + * Check status of a payment intent
3590 + */
3591 + async checkPaymentStatus(paymentIntentId) {
3592 + try {
3593 + logger.info(`Checking status of payment ${paymentIntentId}`);
3594 +
3595 + const paymentIntent = await this.stripe.paymentIntents.retrieve(paymentIntentId);
3596 +
3597 + logger.info(`Payment status: ${paymentIntent.status}`);
3598 + return {
3599 + success: true,
3600 + paymentIntentId: paymentIntent.id,
3601 + status: paymentIntent.status,
3602 + amount: paymentIntent.amount,
3603 + currency: paymentIntent.currency,
3604 + customerId: paymentIntent.customer,
3605 + paymentMethodId: paymentIntent.payment_method
3606 + };
3607 + } catch (error) {
3608 + logger.error(`Error checking payment status: ${error.message}`);
3609 + return {
3610 + success: false,
3611 + error: error.message,
3612 + code: error.code
3613 + };
3614 + }
3615 + }
3616 +
3617 + /**
3618 + * List payment methods for a customer
3619 + */
3620 + async listPaymentMethods(customerId, type = 'card') {
3621 + try {
3622 + logger.info(`Listing ${type} payment methods for customer ${customerId}`);
3623 +
3624 + const paymentMethods = await this.stripe.paymentMethods.list({
3625 + customer: customerId,
3626 + type: type
3627 + });
3628 +
3629 + logger.info(`Found ${paymentMethods.data.length} payment methods`);
3630 + return {
3631 + success: true,
3632 + paymentMethods: paymentMethods.data.map(pm => ({
3633 + id: pm.id,
3634 + type: pm.type,
3635 + createdAt: new Date(pm.created * 1000),
3636 + isDefault: pm.is_default,
3637 + card: type === 'card' ? {
3638 + brand: pm.card.brand,
3639 + last4: pm.card.last4,
3640 + expMonth: pm.card.exp_month,
3641 + expYear: pm.card.exp_year
3642 + } : null
3643 + }))
3644 + };
3645 + } catch (error) {
3646 + logger.error(`Error listing payment methods: ${error.message}`);
3647 + return {
3648 + success: false,
3649 + error: error.message,
3650 + code: error.code
3651 + };
3652 + }
3653 + }
3654 + }
3655 +
3656 + module.exports = PaymentService;
3657 +
3658 + // Example usage in Express.js
3659 + const express = require('express');
3660 + const router = express.Router();
3661 + const PaymentService = require('./payment-service');
3662 + const paymentService = new PaymentService();
3663 +
3664 + // Create payment intent endpoint
3665 + router.post('/create-payment-intent', async (req, res) => {
3666 + const { amount, currency, customerId, description } = req.body;
3667 +
3668 + if (!amount || !currency || !customerId) {
3669 + return res.status(400).json({
3670 + success: false,
3671 + error: 'Missing required parameters'
3672 + });
3673 + }
3674 +
3675 + const result = await paymentService.createPaymentIntent(
3676 + amount,
3677 + currency,
3678 + customerId,
3679 + description
3680 + );
3681 +
3682 + if (result.success) {
3683 + res.json(result);
3684 + } else {
3685 + res.status(400).json(result);
3686 + }
3687 + });
3688 +
3689 + // Create customer endpoint
3690 + router.post('/create-customer', async (req, res) => {
3691 + const { email, name, metadata } = req.body;
3692 +
3693 + if (!email || !name) {
3694 + return res.status(400).json({
3695 + success: false,
3696 + error: 'Email and name are required'
3697 + });
3698 + }
3699 +
3700 + const result = await paymentService.createCustomer(email, name, metadata);
3701 +
3702 + if (result.success) {
3703 + res.json(result);
3704 + } else {
3705 + res.status(400).json(result);
3706 + }
3707 + });
3708 +
3709 + // Process payment endpoint
3710 + router.post('/process-payment', async (req, res) => {
3711 + const {
3712 + amount,
3713 + currency,
3714 + customerId,
3715 + paymentMethodId,
3716 + description
3717 + } = req.body;
3718 +
3719 + if (!amount || !currency || !customerId || !paymentMethodId) {
3720 + return res.status(400).json({
3721 + success: false,
3722 + error: 'Missing required parameters'
3723 + });
3724 + }
3725 +
3726 + const result = await paymentService.processPayment(
3727 + amount,
3728 + currency,
3729 + customerId,
3730 + paymentMethodId,
3731 + description
3732 + );
3733 +
3734 + res.json(result);
3735 + });
3736 +
3737 + // Issue refund endpoint
3738 + router.post('/refund', async (req, res) => {
3739 + const { paymentIntentId, amount, reason } = req.body;
3740 +
3741 + if (!paymentIntentId) {
3742 + return res.status(400).json({
3743 + success: false,
3744 + error: 'Payment intent ID is required'
3745 + });
3746 + }
3747 +
3748 + const result = await paymentService.refundPayment(
3749 + paymentIntentId,
3750 + amount,
3751 + reason
3752 + );
3753 +
3754 + if (result.success) {
3755 + res.json(result);
3756 + } else {
3757 + res.status(400).json(result);
3758 + }
3759 + });
3760 +
3761 + module.exports = router;
3762 + ```
3763 +
3764 + ## 13. Conclusion: Building Robust API Clients
3765 +
3766 + Throughout this guide, we've explored the fundamental concepts of working with APIs and built practical examples. Let's summarize the key principles for creating robust API clients:
3767 +
3768 + ### 1. Follow a Layered Design
3769 +
3770 + Structure your API clients with clear separation of concerns:
3771 +
3772 + - **Transport Layer**: Handles HTTP requests, retries, and error handling
3773 + - **API Interface Layer**: Maps API endpoints to method calls
3774 + - **Business Logic Layer**: Transforms data for your application needs
3775 +
3776 + This separation makes your code more maintainable and testable.
3777 +
3778 + ### 2. Implement Comprehensive Error Handling
3779 +
3780 + No API is 100% reliable. Your client should:
3781 +
3782 + - Catch and categorize different types of errors
3783 + - Implement appropriate retry strategies
3784 + - Provide meaningful error messages
3785 + - Fail gracefully when the API is unavailable
3786 +
3787 + ### 3. Be Mindful of Performance
3788 +
3789 + Consider performance implications:
3790 +
3791 + - Use connection pooling for multiple requests
3792 + - Implement caching where appropriate
3793 + - Batch operations when possible
3794 + - Use asynchronous requests when handling multiple calls
3795 +
3796 + ### 4. Make Security a Priority
3797 +
3798 + Never compromise on security:
3799 +
3800 + - Always use HTTPS
3801 + - Store credentials securely
3802 + - Implement proper authentication
3803 + - Validate all inputs and outputs
3804 + - Follow the principle of least privilege
3805 +
3806 + ### 5. Design for Testability
3807 +
3808 + Make your API clients easy to test:
3809 +
3810 + - Use dependency injection for external services
3811 + - Create interfaces that can be mocked
3812 + - Separate I/O operations from business logic
3813 + - Write unit tests for each component
3814 + - Use integration tests for end-to-end verification
3815 +
3816 + ### 6. Document Your Code
3817 +
3818 + Even internal API clients need documentation:
3819 +
3820 + - Document the purpose of each method
3821 + - Explain expected parameters and return values
3822 + - Provide usage examples
3823 + - Document error handling strategies
3824 + - Keep the documentation up-to-date
3825 +
3826 + ### 7. Be a Good API Citizen
3827 +
3828 + Respect the API provider's rules:
3829 +
3830 + - Follow rate limits
3831 + - Minimize unnecessary requests
3832 + - Implement exponential backoff for retries
3833 + - Keep your client libraries updated
3834 + - Review API changes and deprecation notices
3835 +
3836 + ### 8. Prepare for Evolution
3837 +
3838 + APIs change over time, so design for adaptability:
3839 +
3840 + - Version your own client code
3841 + - Create abstractions that can accommodate API changes
3842 + - Develop a strategy for handling breaking changes
3843 + - Test against API sandbox environments when available
3844 +
3845 + ### Final Thoughts
3846 +
3847 + Building effective API clients is both an art and a science. The best implementations balance technical requirements with user needs, creating interfaces that hide complexity while providing powerful functionality.
3848 +
3849 + As you develop your skills, remember that the most successful API integrations are those that users barely notice. They should work reliably, perform efficiently, and handle errors gracefully without requiring users to understand the underlying API mechanics.
3850 +
3851 + By applying the principles covered in this guide, you'll be well-equipped to build API clients that stand the test of time and deliver exceptional value to your applications and users.
3852 +
3853 + ## 14. Further Resources
3854 +
3855 + To continue your learning about APIs, here are some valuable resources:
3856 +
3857 + ### Books
3858 +
3859 + - "RESTful Web APIs" by Leonard Richardson, Mike Amundsen, and Sam Ruby
3860 + - "Designing Web APIs" by Brenda Jin, Saurabh Sahni, and Amir Shevat
3861 + - "API Design Patterns" by JJ Geewax
3862 +
3863 + ### Online Courses
3864 +
3865 + - "API Development in Python" (Udemy)
3866 + - "RESTful API with HTTP and JavaScript" (Coursera)
3867 + - "API Security" (Pluralsight)
3868 +
3869 + ### Documentation and Specifications
3870 +
3871 + - [OpenAPI Specification](https://swagger.io/specification/)
3872 + - [JSON:API Specification](https://jsonapi.org/)
3873 + - [OAuth 2.0 Documentation](https://oauth.net/2/)
3874 +
3875 + ### Tools
3876 +
3877 + - [Postman](https://www.postman.com/) - API development and testing
3878 + - [Swagger UI](https://swagger.io/tools/swagger-ui/) - API documentation
3879 + - [Charles Proxy](https://www.charlesproxy.com/) - HTTP debugging proxy
3880 +
3881 + ### API Directories
3882 +
3883 + - [ProgrammableWeb](https://www.programmableweb.com/)
3884 + - [RapidAPI Hub](https://rapidapi.com/)
3885 + - [Public APIs](https://github.com/public-apis/public-apis)
3886 +
3887 + Keep exploring, and happy coding!
Newer Older

Powered by Opengist ⋅ Load: 451ms⋅

English