Chapter 1.4: REST API Structure
Study time: 45 minutes
1. REST API: The Architecture of a Space Station
Imagine a space station where each module has:
-
A standard docking port (a unified interface)
-
Clear specialization (living quarters, laboratory, storage)
-
A coordinate system (precise location)
A REST (Representational State Transfer) API works on the same principles:
-
A unified interface for all resources
-
Clear separation of components
-
Addressing via URI (space coordinates)
💡 Key idea:
Each resource (planets, rockets, astronauts) has a unique URL and interacts through HTTP methods.
2. The 6 Principles of REST in a Space Analogy
REST Principle | Analogy on the ISS | Meaning for the API |
---|---|---|
Unified Interface | Standard docking ports | The same rules for all requests |
Stateless | Each command is self-sufficient | The server does not store client state |
Caching | Local supplies of provisions | Saving frequent responses |
Client-Server | Clear separation: MCC ↔ Station | Independent development of components |
Layered System | Relay satellites | Proxies, load balancers |
Code on Demand | Loading software for experiments | (Optional) Transferring scripts |
3. Resources and URIs: Space Coordinates
Each object in the API is a resource with a unique address:
https://api.spacexdata.com/v4/ ← Base URL
rockets/ ← Collection of rockets
rockets/5e9d0d95eda69973a809d1ec ← A specific rocket (by ID)
Examples of space resources:
GET /stars
→ List of starsGET /stars/sirius
→ Data about SiriusPOST /satellites
→ Launch a new satellitePUT /missions/artemis
→ Update a mission
URI hierarchy diagram:
[Base URL]
├── /planets → Collection of planets
│ ├── /mars → "Mars" resource
│ └── /venus → "Venus" resource
└── /launches → Collection of launches
├── /upcoming → Sub-collection
└── /latest → Resource
4. CRUD Operations via HTTP Methods
Operation | HTTP Method | Example (Space Station) | Server Response |
---|---|---|---|
Create | POST |
Send a new module | 201 Created |
Read | GET |
Request data about a module | 200 OK |
Update | PUT |
Reconfigure a module | 200 OK |
Delete | DELETE |
Undock an old module | 204 No Content |
⚡ Code Example (Adding a satellite):
import requests
# We use a test service that simulates the creation of a resource
new_post = {
"title": "New Telescope Launch",
"body": "Hubble-2 is ready for deployment.",
"userId": 1
}
# Conditional API key for demonstrating headers
headers = {
"Authorization": "Bearer YOUR_DEMO_KEY",
"Content-Type": "application/json; charset=UTF-8"
}
response = requests.post(
"https://jsonplaceholder.typicode.com/posts",
json=new_post,
headers=headers
)
if response.status_code == 201:
print("✅ Post about the new satellite created successfully!")
print("Server response:")
print(response.json())
else:
print(f"❌ Error! Status: {response.status_code}")
5. API Versioning: The Evolution of the Station
Just as the ISS is updated (Zarya module → Nauka), APIs change versions:
- In the URL:
https://api.spacex.com/v4/rockets
- In the headers:
Accept: application/vnd.spacex-v5+json
Why it's important:
- v1: Basic functionality
- v2: New fields added
- v3: Response structure changed
⚠️ Tip: Always specify the version in requests, otherwise the "docking" may fail!
6. Hypermedia (HATEOAS): Navigation in Space
The API response contains links to related resources - like a map of the station:
{
"id": "iss",
"name": "International Space Station",
"crew": 7,
"_links": {
"self": { "href": "/stations/iss" },
"modules": { "href": "/stations/iss/modules" },
"schedule": { "href": "/stations/iss/schedule" }
}
}
Quiz for reinforcement
🚀 Chapter summary:
A REST API is a standardized "space station architecture" for web services. Remember:
- Resources = Objects (rockets, planets)
- URI = Object coordinates
- HTTP methods = Control commands
- Versions = Station upgrades
Final preparation! In the next chapter, we will launch a "test probe" - we will learn how to test an API using Postman.
📌 Practice: Study the structure of the SpaceX API and try to execute:
GET https://api.spacexdata.com/v4/launches/latest
— pay attention to the URI and the JSON structure!