Introduction

Nota (PT-BR): documentação técnica em inglês (fiel ao magento/devdocs-m1). Abaixo estão os fundamentos da REST API.

Overview

The Magento REST API is a set of functions to which developers can perform requests and receive responses via the HTTP protocol. All REST resources are located at https://magentohost/api/rest/.

Capabilities

• Customers
• Customer addresses
• Products
• Sales orders (with addresses, items and comments)
• Inventory (stock items)

HTTP Verbs

• GET — retrieve a resource
• POST — create a resource
• PUT — update a resource
• DELETE — remove a resource

Output Formats

Both XML and JSON are supported. Use the Accept header to select the format — text/xml or application/json.

Pagination

• Default items: 10
• Max items per page: 100
• Query params: page, limit, order, dir

GET Filters

Use these query parameters to filter, paginate and sort GET responses.

Pagination & sorting

• page — page number
• limit — items per page (max 100)
• order — field to sort by
• dir — sort direction (asc / dsc)

Filter operators

• filter — generic filter
• neq — not equal
• in / nin — matches / does not match any of
• gt / lt — greater / less than
• from / to — range

Examples

GET /api/rest/products?filter[1][attribute]=price&filter[1][from]=150&filter[1][to]=350
GET /api/rest/customers?filter[1][attribute]=email&filter[1][eq]=john@example.com

Dica (PT-BR): para valores com espaço, substitua espaços por %20.

Common HTTP Status Codes

• 200 OK — Successful request
• 201 Created — Resource (partially) created
• 207 Multi-Status — Multiple status responses
• 400 Bad Request — Validation errors, invalid requests, paging/filtering problems
• 403 Forbidden — Access denied
• 404 Not Found — Resource not found
• 405 Method Not Allowed — HTTP method not supported for this resource
• 500 Internal Error — Unhandled errors

JSON error example

{
    "messages": {
        "error": [
            {"code": 404, "message": "Resource not found."}
        ]
    }
}

Response Formats

Use the Accept header to negotiate:

• text/xml — responses wrapped in <magento_api>
• application/json — JSON mapping of the XML structure

Permission Settings

After successful authentication, the access token identifies the user type and user ID used for every call.

Access Levels

• Guest — unauthenticated apps accessing only public resources
• Customer — registered, logged-in user with access to personal and public resources
• Admin — store owner with full permissions

Setting Up ACL

1. REST Roles — define which resources each role can access (System > Web Services > REST - Roles).
2. REST Attributes — define which attributes can be read/written per role (System > Web Services > REST - Attributes).

Dica (PT-BR): exponha o mínimo possível — libere apenas os atributos estritamente necessários para cada papel.