Skip to content

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 stars
  • GET /stars/sirius → Data about Sirius
  • POST /satellites → Launch a new satellite
  • PUT /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

1. REST stands for:

2. The "Stateless" principle means:

3. The URI for getting data about the Falcon Heavy rocket:

4. The method for a full update of a resource:

5. HATEOAS in an API is:


🚀 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!