REST API Introduction

What is REST?

REST (Representational State Transfer) is an architectural style for APIs.

REST Principles

1. Client-Server: Separation of concerns
2. Stateless: No client context stored on server
3. Cacheable: Responses must define cacheability
4. Uniform Interface: Standardized operations
5. Layered System: Client can't tell if connected to end server

Magento REST API

Base URL: https://your-store.com/rest/

Default store: /rest/V1/
Specific store: /rest/{store_code}/V1/

Examples:
https://your-store.com/rest/V1/products
https://your-store.com/rest/default/V1/products
https://your-store.com/rest/germany/V1/products

API Versions

# Current API version: V1
# Endpoint format: /rest/{store}/V1/{resource}

# Example endpoints:
GET /rest/V1/products
POST /rest/V1/products
GET /rest/V1/customers
GET /rest/V1/orders

Common Resources

Resource Relationships

Products → Categories
Customers → Orders
Orders → Items → Products
Carts → Items → Products

Nested Resources

# Get products in category
GET /rest/V1/categories/{categoryId}/products

# Get customer orders
GET /rest/V1/customers/{customerId}/orders

# Get order items
GET /rest/V1/orders/{orderId}/items

Search Resources

# Search products
GET /rest/V1/products?searchCriteria[filter_groups][0][filters][0][field]=name&searchCriteria[filter_groups][0][filters][0][value]=%25shirt%25&searchCriteria[filter_groups][0][filters][0][condition_type]=like

# Search orders
GET /rest/V1/orders?searchCriteria[filter_groups][0][filters][0][field]=status&searchCriteria[filter_groups][0][filters][0][value]=pending

Method Overview

GET Requests

# Get all products
curl -X GET 'https://store.com/rest/V1/products' \
     -H 'Authorization: Bearer {token}'

# Get specific product
curl -X GET 'https://store.com/rest/V1/products/SKU-123' \
     -H 'Authorization: Bearer {token}'

# Get with search criteria
curl -X GET 'https://store.com/rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=sku&searchCriteria[filterGroups][0][filters][0][value]=SKU-123' \
     -H 'Authorization: Bearer {token}'

POST Requests

# Create product
curl -X POST 'https://store.com/rest/V1/products' \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/json' \
     -d '{
         "product": {
             "sku": "SKU-123",
             "name": "Test Product",
             "price": 29.99,
             "status": 1,
             "visibility": 4,
             "type_id": "simple"
         }
     }'

PUT Requests

# Update product
curl -X PUT 'https://store.com/rest/V1/products/SKU-123' \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/json' \
     -d '{
         "product": {
             "price": 39.99
         }
     }'

DELETE Requests

# Delete product
curl -X DELETE 'https://store.com/rest/V1/products/SKU-123' \
     -H 'Authorization: Bearer {token}'

Request Content Types

# JSON (most common)
-H 'Content-Type: application/json'

# Form data
-H 'Content-Type: application/x-www-form-urlencoded'

# Multipart (file upload)
-H 'Content-Type: multipart/form-data'

Response Content Types

# JSON response (default)
-H 'Accept: application/json'

# XML response
-H 'Accept: application/xml'

JSON Format

{
    "product": {
        "id": 1,
        "sku": "SKU-123",
        "name": "Test Product",
        "price": 29.99,
        "status": 1,
        "visibility": 4,
        "type_id": "simple",
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-01 00:00:00"
    }
}

Error Response Format

{
    "message": "Invalid product data",
    "errors": [
        {
            "message": "The SKU is required.",
            "field": "sku",
            "code": 0
        }
    ]
}

Pagination Headers

# Response headers
X-Total-Count: 100
X-Page-Size: 20
X-Current-Page: 1