diff --git a/docs/content/api/rest/assets/images/rest_test001.png b/docs/content/api/rest/assets/images/rest_test001.png new file mode 100644 index 00000000000..6d9fe290edc Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test001.png differ diff --git a/docs/content/api/rest/assets/images/rest_test003.png b/docs/content/api/rest/assets/images/rest_test003.png new file mode 100644 index 00000000000..8463571f30b Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test003.png differ diff --git a/docs/content/api/rest/assets/images/rest_test004.png b/docs/content/api/rest/assets/images/rest_test004.png new file mode 100644 index 00000000000..89b567b4200 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test004.png differ diff --git a/docs/content/api/rest/assets/images/rest_test005.png b/docs/content/api/rest/assets/images/rest_test005.png new file mode 100644 index 00000000000..a811bda02ba Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test005.png differ diff --git a/docs/content/api/rest/assets/images/rest_test006.png b/docs/content/api/rest/assets/images/rest_test006.png new file mode 100644 index 00000000000..beda9b1b62e Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test006.png differ diff --git a/docs/content/api/rest/assets/images/rest_test007.png b/docs/content/api/rest/assets/images/rest_test007.png new file mode 100644 index 00000000000..100df5ac753 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test007.png differ diff --git a/docs/content/api/rest/assets/images/rest_test008.png b/docs/content/api/rest/assets/images/rest_test008.png new file mode 100644 index 00000000000..77d03f03910 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test008.png differ diff --git a/docs/content/api/rest/assets/images/rest_test009.png b/docs/content/api/rest/assets/images/rest_test009.png new file mode 100644 index 00000000000..9cf27a7574e Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test009.png differ diff --git a/docs/content/api/rest/assets/images/rest_test010.png b/docs/content/api/rest/assets/images/rest_test010.png new file mode 100644 index 00000000000..abcadf683f2 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test010.png differ diff --git a/docs/content/api/rest/assets/images/rest_test011.png b/docs/content/api/rest/assets/images/rest_test011.png new file mode 100644 index 00000000000..9d59663a1e2 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test011.png differ diff --git a/docs/content/api/rest/assets/images/rest_test012.png b/docs/content/api/rest/assets/images/rest_test012.png new file mode 100644 index 00000000000..8dc2b8efaec Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test012.png differ diff --git a/docs/content/api/rest/assets/images/rest_test_authheader.png b/docs/content/api/rest/assets/images/rest_test_authheader.png new file mode 100644 index 00000000000..61379c2eb7a Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test_authheader.png differ diff --git a/docs/content/api/rest/assets/images/rest_test_insert.png b/docs/content/api/rest/assets/images/rest_test_insert.png new file mode 100644 index 00000000000..1a9e46be080 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test_insert.png differ diff --git a/docs/content/api/rest/assets/images/rest_test_oauth_tab.png b/docs/content/api/rest/assets/images/rest_test_oauth_tab.png new file mode 100644 index 00000000000..ae7f02d43f1 Binary files /dev/null and b/docs/content/api/rest/assets/images/rest_test_oauth_tab.png differ diff --git a/docs/content/api/rest/common_http_status_codes.md b/docs/content/api/rest/common_http_status_codes.md new file mode 100644 index 00000000000..4f0363d2bc9 --- /dev/null +++ b/docs/content/api/rest/common_http_status_codes.md @@ -0,0 +1,44 @@ +# Common HTTP status codes + +HTTP status codes are an essential part of the REST concept. You can get familiar with all of them on [Wikipedia](http://en.wikipedia.org/wiki/List_of_http_status_codes). + +The Magento API attempts to return appropriate HTTP status codes for all requests. Any information is returned in the form of a standard HTTP response with an HTTP status code describing the error and the body message. + +## HTTP Status Codes + +The following table contains possible common HTTP status codes: + +| Status Code | Message | +|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 200 OK | - | +| 201 Created | Resource was partially created | +| 207 Multi-Status | - | +| 400 Bad Request | Resource data pre-validation error.
Resource data invalid.
The request data is invalid.
Resource collection paging error.
The paging limit exceeds the allowed number.
Resource collection ordering error.
Resource collection filtering error.
Resource collection including additional attributes error. | +| 403 Forbidden | Access denied. | +| 404 Not Found | Resource not found. | +| 405 Method Not Allowed | Resource does not support method.
Resource method not implemented yet. | +| 500 Internal Error | Unhandled simple errors.
Resource internal error. | + +## Error Messages + +When the Magento API returns an error message, it returns it in your requested format. For example, an error in the XML format might look like the following: + +```xml + + + + + + 404 + Resource not found. + + + + +``` + +An error in the JSON format might look like the following: + +```json +{"messages":{"error":[{"code":404,"message":"Resource not found."}]}} +``` diff --git a/docs/content/api/rest/get_filters.md b/docs/content/api/rest/get_filters.md new file mode 100644 index 00000000000..90e6054d951 --- /dev/null +++ b/docs/content/api/rest/get_filters.md @@ -0,0 +1,118 @@ +# Use filters + +_JSON responses on this page contributed by Tim Reynolds._ + +Some requests use GET parameters in the URL. These are as follows: + +## filter + +Specifies the filters for returned data. + +## page + +Specifies the page number which items will be returned. + +!!! example + ``` + https://om.ddev.site/api/rest/products?page=1 + ``` +## order, dir + +Specifies the sort order of returned items and the order direction: `asc` - returns items in the ascending order; `dsc` - returns items in the descending order. + +!!! example + ``` + https://om.ddev.site/api/rest/products?order=name&dir=dsc + https://om.ddev.site/api/rest/products?order=name&dir=asc + ``` +## limit + +Limits the number of returned items in the response. Note that by default, 10 items are returned in the response. The maximum number is 100 items. + +!!! example + ``` + https://om.ddev.site/api/rest/products?limit=2 + ``` + +## neq + +"not equal to" - returns items with the specified attribute that is not equal to the defined value. + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][neq]=3 + ``` + +## in + +"equals any of" - returns items that are equal to the item(s) with the specified attribute(s). + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][in]=3 + ``` + +## nin + +"not equals any of" - returns items excluding the item with the specified attribute. + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][nin]=3 + ``` + +## gt + +"greater than" - returns items with the specified attribute that is greater than the defined value. + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][gt]=3 + https://om.ddev.site/api/rest/products?filter[1][attribute]=price&filter[1][gt]=300 + ``` + +## lt + +"less than" - returns items with the specified attribute that is less than the defined value. + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][lt]=4 + ``` + +## from, to + +Specifies the range of attributes according to which items will be returned. + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=entity_id&filter[1][from]=1&filter[1][to]=3 + https://om.ddev.site/api/rest/products?filter[1][attribute]=price&filter[1][from]=150&filter[1][to]=350 + ``` + +## Whitespaces + +If the attribute value consists of several words separated by a whitespace, the '%20' sign is used: + +!!! example + ``` + https://om.ddev.site/api/rest/products?filter[1][attribute]=name&filter[1][in]=BlackBerry%208100%20Pearl + ``` + +## Example 1 + +For example, to filter products with the description equal to simple01: + +!!! example + ``` + https://om.ddev.site/api/rest/products/?order=entity_id&filter[0][attribute]=description&filter[0][in][0]=simple01 + ``` + +## Example 2 + +To filter customers by email address: + +!!! example + ``` + https://om.ddev.site/api/rest/customers?filter[1][attribute]=email&filter[1][in][0]=ryan@test.com + ``` diff --git a/docs/content/api/rest/http_methods.md b/docs/content/api/rest/http_methods.md new file mode 100644 index 00000000000..678ad70d6e8 --- /dev/null +++ b/docs/content/api/rest/http_methods.md @@ -0,0 +1,59 @@ +# HTTP methods + +Accessing API is performed via HTTP. When you enter a URL into a web browser address bar, the browser performs an HTTP GET request to the URL. This usually returns a web page in the form of an HTTP response that the browser displays. But the GET method is one of several HTTP request methods. Magento REST API uses the four main HTTP methods: GET, POST, PUT, and DELETE. The most widespread methods are GET and POST. The other methods are less known but they became widely known due to the popularity of REST web services. An important concept of the REST architecture is that different HTTP request methods perform different actions when applied to the same URL. + +For example: + +``` +GET https://om.ddev.site/rest/customers/123 +``` + +will retrieve information about the specified customer; + +``` +DELETE https://om.ddev.site/rest/customers/123 +``` + +will delete the specified customer. + +## GET + +**Retrieving Resources with the HTTP GET Method** + +The HTTP GET method is defined in section 9.3 of the [RFC2616](http://www.ietf.org/rfc/rfc2616.txt) document: + +> The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process. + +You can retrieve a representation of a resource by getting its URL. + +## POST and PUT + +**Creating or Updating Resources with the HTTP POST and PUT Methods** + +The POST method is defined in section 9.5 of the [RFC2616](http://www.ietf.org/rfc/rfc2616.txt) document: + +> The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions: +> +> * Annotation of existing resources; +> +> * Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles; +> +> * Providing a block of data, such as the result of submitting a form, to a data-handling process; +> +> * Extending a database through an append operation. + +The PUT method is defined in section 9.6 of the [RFC2616](http://www.ietf.org/rfc/rfc2616.txt) document: + +> The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. + +Creating or updating a resource involves performing an HTTP POST or HTTP PUT to a resource URL. + +## DELETE + +**Deleting Resources with the HTTP DELETE Method** + +The DELETE method is defined in section 9.7 of the [RFC2616](http://www.ietf.org/rfc/rfc2616.txt) document: + +> The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. + +Deleting a resource is performed by means of making an HTTP DELETE request to the resource URL. \ No newline at end of file diff --git a/docs/content/api/rest/resources/customers.md b/docs/content/api/rest/resources/customers.md new file mode 100644 index 00000000000..cd8829e2feb --- /dev/null +++ b/docs/content/api/rest/resources/customers.md @@ -0,0 +1,268 @@ +\--- layout: v1x\_rest title: Customers --- JSON responses on this page contributed by Tim Reynolds + +* [REST API: Customers](#RESTAPI-Resource-Customers-RESTAPI-Customers) + * [URI: /customers](#RESTAPI-Resource-Customers-URI--customers) + * [HTTP Method: GET /customers](#RESTAPI-Resource-Customers-HTTPMethod-GET-customers) + * [HTTP Method: POST /customers](#RESTAPI-Resource-Customers-HTTPMethod-POST-customers) + * [HTTP Method: PUT /customers](#RESTAPI-Resource-Customers-HTTPMethod-PUT-customers) + * [HTTP Method: DELETE /customers](#RESTAPI-Resource-Customers-HTTPMethod-DELETE-customers) +* [REST API: Customer](#RESTAPI-Resource-Customers-RESTAPI-Customer) + * [URI: /customers/:customerId](#RESTAPI-Resource-Customers-URI--customers--customerId) + * [HTTP Method: GET /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-GET-customers--customerId) + * [HTTP Method: POST /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-POST-customers--customerId) + * [HTTP Method: PUT /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-PUT-customers--customerId) + * [HTTP Method: DELETE /customers/:customerId](#RESTAPI-Resource-Customers-HTTPMethod-DELETE-customers--customerId) + +## Customers + +#### URI: /customers + +Allows you to create and retrieve customers. + +**URL Structure**: http://om.ddev.site/api/rest/customers +**Version**: 1 + +### HTTP Method GET + +**Description**: Allows you to retrieve the list of existing customers. +**Notes:**: Only Admin user can retrieve the list of customers with all their attributes. + +**Authentication**: Admin
+**Default Format**: XML
+**Parameters**: _No Parameters_ + +!!! Example + ``` + GET http://om.ddev.site/api/rest/customers + ``` + +#### Response body: XML + +```xml + + + + 2 + 1 + test@example.com + 1 + 2012-03-22 14:15:54 + 1 + john + Doe + Default Store View + + + 4 + 1 + earl@example.com + 1 + 2012-03-28 13:54:04 + 0 + Earl + Hickey + Admin + + +``` + +#### Response body: JSON + +```json +{ + "2": { + "entity_id": "2", + "website_id": "1", + "email": "test@example.com", + "group_id": "1", + "created_at": "2012-03-22 14:15:54", + "disable_auto_group_change": "1", + "firstname": "john", + "lastname": "Doe", + "created_in": "Admin", + "prefix": null, + "suffix": null, + "taxvat": null, + "dob": "2001-01-03 00:00:00", + "reward_update_notification": "1", + "reward_warning_notification": "1", + "gender": "1" + }, + "4": { + "entity_id": "4", + "website_id": "1", + "email": "earl@example.com", + "group_id": "1", + "created_at": "2013-03-28 18:59:41", + "disable_auto_group_change": "0", + "firstname": "Earl", + "lastname": "Hickey", + "created_in": "Admin", + "prefix": null, + "suffix": null, + "taxvat": null, + "dob": "2012-03-28 13:54:04", + "reward_update_notification": "1", + "reward_warning_notification": "1", + "gender": "1" + } +} +``` + +### HTTP Method POST + +**Description**: Allows you to create a new customer. + +**Authentication**: Admin
+**Default Format**: XML
+**Parameters**: + +| Name | Description | Required | Type | Example Value | +|---------------------------|------------------------------------------------------------------------------|----------|--------|-------------------| +| firstname | The customer first name | required | string | John | +| lastname | The customer last name | required | string | Doe | +| email | The customer email address | required | string | johny@example.com | +| password | The customer password. The password must contain minimum 7 characters | required | string | 123123q | +| website_id | Website ID | required | int | 1 | +| group_id | Customer group ID | required | int | 1 | +| disable_auto_group_change | Defines whether the automatic group change for the customer will be disabled | optional | int | 0 | +| prefix | Customer prefix | optional | string | Mr. | +| middlename | Customer middle name or initial | optional | string | R. | +| suffix | Customer suffix | optional | string | Sr. | +| taxvat | Customer Tax or VAT number | optional | string | GB999 9999 73 | + +**Notes**: The list of parameters may change depending on the attributes settings in **Customers** > **Attributes** > **Manage Customer Attributes** page in Magento Admin Panel. For example, a required status of the **middlename** attribute (Middle Name/Initial) may be changed to 'YES". Please note that managing customer attributes is available only in Magento Enterprise Edition. + +!!! Example + ``` + POST http://om.ddev.site/api/rest/customers + ``` + +#### Request body + +```xml + + + Earl + Hickey + 123123q + earl@example.com + 1 + 1 + +``` + +#### Response + +If the customer was created successfully, we receive **Response HTTP Code** = 200, empty **Response Body** and **Location** header like `/api/rest/customers/555` where `555` - an entity id of the new customer. + +### HTTP Method PUT + +**Description**: Not allowed + +### HTTP Method DELETE + +**Description**: Not allowed + +## Customer + +#### URI: /customers/:customerId + +Allows you to manage existing customers. + +**URL Structure**: http://om.ddev.site/api/rest/customers/:customerId +**Version**: 1 + +### HTTP Method GET + +**Description**: Allows you to retrieve information on an existing customer. +**Notes:**: The list of attributes that will be returned for customers is configured in the Magento Admin Panel. The Customer user type has access only to his/her own information. Also, Admin can add additional non-system customer attributes by selecting **Customers** > **Attributes** > **Manage Customer Attributes**. If these attributes are set as visible on frontend, they will be returned in the response. Also, custom attributes will be returned in the response only after the customer information is updated in the Magento Admin Panel or the specified custom attribute is updated via API (see the PUT method below). Please note that managing customer attributes is available only in Magento Enterprise Edition. + +**Authentication**: Admin, Customer
+**Default Format**: XML
+**Parameters**: _No Parameters_ + +!!! Example + ``` + GET http://om.ddev.site/api/rest/customers/2 + ``` + +**Response Body**: + + + +2 +1 +test@example.com +1 +2012-03-22 14:15:54 +1 +Default Store View +john +Doe +2012-03-22 14:15:56 + + +**response example: json** + +get [http://om.ddev.site/api/rest/customers/141](http://om.ddev.site/api/rest/customers) + +**response body**: + +{ +"entity\_id": "2", +"website\_id": "1", +"email": "test@example.com", +"group\_id": "1", +"created\_at": "2012-03-22 14:15:54", +"disable\_auto\_group\_change": "1", +"created\_in": "English", +"firstname": "john", +"lastname": "Doe" +} + + +### HTTP Method POST + +**Description**: Not allowed. + +### HTTP Method PUT + +**Description**: Allows you to update an existing customer.
+**Notes**: The list of attributes that will be updated for customer is configured in the Magento Admin Panel. The Customer user type has access only to his/her own information. + +**Authentication**: Admin, Customer
+**Default Format**: XML
+**Parameters**: You must specify only those parameters which you want to update. Parameters that are not defined in the request body will preserve the previous values. The `website_id` and `created_in` attributes are not allowed for updating. + + +!!! Example + ``` + PUT http://om.ddev.site/api/rest/customers/2 + ``` + +#### Request Body + +```xml + + + Earl + Hickey + customerss@example.com + 1 + +``` + +### HTTP Method DELETE + +**Description**: Allows you to delete an existing customer.
+**Notes**: Admin only can delete a customer. + +**Authentication**: Admin
+**Default Format**: XML
+**Parameters**: _No Parameters_ + +!!! Example + ``` + DELETE https://om.ddev.site/api/rest/customers/2 + ``` diff --git a/docs/content/api/rest/resources/products/product_categories.md b/docs/content/api/rest/resources/products/product_categories.md new file mode 100644 index 00000000000..678075d0b49 --- /dev/null +++ b/docs/content/api/rest/resources/products/product_categories.md @@ -0,0 +1,80 @@ +# Product Categories + +## URI: /products/productid/categories + +Allows you to retrieve information about assigned categories, assign, and unassign a category from/to a product. + +**URL Structure**: https://om.ddev.site/api/rest/products/productid/categories
+**Version**: 1 + +### HTTP Method: GET + +**Description**: Allows you to retrieve information about categories assigned to the specified product. + +**Authentication**: Admin, Customer
+**Default Format**: JSON
+**Parameters**: _No Parameters_ + +!!! Example + ``` + GET https://om.ddev.site/api/rest/products/8/categories + ``` + +#### Response Body + +``` +{ + category_id: 8 +} +``` + +### HTTP Method: POST + +**Description**: Allows you to assign a category to a specified product. + +**Authentication**: Admin
+**Default Format**: JSON
+**Parameters**: + +| Name | Description | Required | Type | Example Value | +|--------------|-----------------|:---------|:-----|:--------------| +| category_id | The category ID | required | int | 2 | + + +!!! Example + ``` + POST https://om.ddev.site/api/rest/products/8/categories + ``` + +#### Request Body + +```json +{ + "category_id":"2" +} +``` + +As a result, the category with ID equal to 2 will be assigned to the specified product. + +## URI: /products/productid/categories/categoryid + +### HTTP Method: DELETE + +**Description**: Allows you to unassign a category from a specified product. + +**Authentication**: Admin
+**Default Format**: JSON
+**Parameters**: _No Parameters_ + +!!! Example + ``` + DELETE https://om.ddev.site/api/rest/products/8/categories/2 + ``` + +## HTTP Status Codes + +| Status Code | Message | Description | +|-------------|--------------------------------------------------------------------|---------------------------------------------------------------------------------------| +| 400 | Product is already assigned to category | The message is returned when the required category is already assigned to the product | +| 400 | Category not found | The specified category is not found | +| 405 | Resource method not implemented yet | The specified method is not implemented yet | diff --git a/docs/content/api/rest/response_formats.md b/docs/content/api/rest/response_formats.md new file mode 100644 index 00000000000..de29bf9ebae --- /dev/null +++ b/docs/content/api/rest/response_formats.md @@ -0,0 +1,112 @@ +# Response Formats + +If you make a Magento API call, you are guaranteed to receive some kind of a response. If you make a successful call, you will receive an HTTP response with a 200 OK status. + +You can view the response data from any Magento API call in one of the following two formats: + +* XML +* JSON + +The format of returned data is defined in the request header. The format you choose depends on what you are familiar with most or tools available to you. + +## XML Format + +The XML response format is a simple XML block. +To set the response format to XML, add the Accept request header with the `text/xml` value. + +A successful call will return the following response (example of retrieving information about stock items): + +```xml + + + + 1 + 1 + 1 + 99.0000 + + + + 2 + 2 + 1 + 100.0000 + + + +``` + +If an error occurs, the call may return the following response: + +```xml + + + + + + 404 + Resource not found. + + + + +``` + +## JSON Format + +To set the response format to JSON, add the Accept request header with the `application/json` value. + +### Response Structure + +The JSON objects represent a direct mapping of the XML block from the XML response format. + +A simple XML error + +```xml + + + + 404 + Resource not found. + + + +``` + +will be transformed to + +```json +{"messages":{"error":[{"code":404,"message":"Resource not found."}]}} +``` + +### JSON Responses + +A successful API call to the Stock Items resource will return the following XML response: + +```xml + + + + 1 + 1 + 1 + 99.0000 + + + + 2 + 2 + 1 + 100.0000 + + + +``` + +The JSON equivalent will be as follows: + +```json +[{"item_id":"1","product_id":"1","stock_id":"1","qty":"99.0000","low_stock_date":null},{"item_id":"2","product_id":"2","stock_id":"1","qty":"100.0000","low_stock_date":null}] +``` + +The list of HTTP status codes that are returned in the API response is described in the [Common HTTP Status Codes](common_http_status_codes.md "Common HTTP Status Codes") part of the documentation. There, you can find the list of codes themselves together with their description. \ No newline at end of file diff --git a/docs/content/api/rest/testing_rest_resources.md b/docs/content/api/rest/testing_rest_resources.md new file mode 100644 index 00000000000..7420b03ab63 --- /dev/null +++ b/docs/content/api/rest/testing_rest_resources.md @@ -0,0 +1,98 @@ +# Testing + +Three steps are required for utilizing REST API resources: + +* [Authenticate the user](http://www.magentocommerce.com/api/rest/authentication/oauth_authentication.html "OAuth Authentication") (receive the access token for further steps); +* Configure the [permissions for operations](http://www.magentocommerce.com/api/rest/permission_settings/roles_configuration.html "REST Roles Configuration") and [attributes](http://www.magentocommerce.com/api/rest/permission_settings/attributes_configuration.html "REST Attributes Configuration") for the type of the user; +* Make an API call. + +The following headers are required for the call: + +* Authorization +* Version +* Accept +* Content-type + +The following parameters must be provided in the Authorization header for the call: + +* oauth\_signature\_method +* oauth\_version +* oauth\_nonce +* oauth\_timestamp +* oauth\_consumer\_key +* oauth\_token +* oauth\_signature + +#### Testing REST resources with the [REST Client](https://addons.mozilla.org/en-US/firefox/addon/restclient/) plugin for the Mozilla Firefox browser. + +1. Open the REST Client. +2. From the Authentication drop-down, select **OAuth**. + ![](assets/images/rest_test001.png) +3. In the OAuth window, on the Signature for the request tab, fill in the following fields: + * **Consumer key**: Enter the **Key** value provided when you created the consumer in Magento Admin Panel. + * **Consumer secret**: Enter the **Secret** value provided when you created the consumer in Magento Admin Panel. + * **Access token**: Enter the oauth\_token value received when you authenticated the application. + * **Access token secret**: Enter the oauth\_token\_secret value received when you authenticated the application. +4. On the OAuth setting tab, define the following options: ![](assets/images/rest_test_oauth_tab.png) + * **Signature Methods**: From the drop-down list, select which method will be used for signatures (HMAC-SHA1 or PLAINTEXT). + * **oAuth Version**: From the drop-down list, select the **1.0** option (REST API supports OAuth 1.0a). + * Leave the **Realm**, **oAuth Nonce**, and **oAuth Timestamp** values set by default. +5. Click **Save** and wait for the confirmation dialog to close. + +6. Return to the Signature for the request tab and select **Insert > Insert as header**. ![](assets/images/rest_test_insert.png) + + An authorization header is created on the main page of REST Client. + + ![](assets/images/rest_test_authheader.png) + **NOTE**: Click the header with authorization data and click **Auto refresh** in the opened pop-up in order to generate new values for oauth\_nonce, oauth\_timestamp, and oauth\_signature at each request. + ![](assets/images/rest_test003.png)11. From the **Headers** drop-down, select **Custom Header**. + ![](assets/images/rest_test004.png) +12. In the **Request Header** window, enter "Content-Type" in the **Name** field and "text/xml" in the **Value** field (if you want to use the XML data format). To use the JSON request data format, enter application/json instead of the text/xml value. +13. Click **Okay**. + ![](assets/images/rest_test005.png) + +**Example: Retrieving the List of Products** + +1. From the **Method** drop-down list, select the **GET** option. +2. In the **URL** field, enter the following URL: https://om.ddev.site/api/rest/products. You can limit the number of products returned in the response. To set the limit to 4, enter the following URL: https://om.ddev.site/api/rest/products?limit=4 +3. Click **Send**. Information about all products will be displayed in the response body. Example is as follows: + ![](assets/images/rest_test006.png) + +#### Testing REST resources with the [Advanced REST Client](https://chrome.google.com/webstore/detail/hgmloofddffdnphfgcellkdfbfbjeloo) for Google Chrome browser. + +1. Open the Advanced REST Client Application. + ![](assets/images/rest_test007.png) +2. In the **Headers** box, select the **Form** tab. +3. In the first field, start typing _authorization_. An **Authorization** popup appears. Click it. + ![](assets/images/rest_test008.png) +4. When you click the fields next to the Authorization header, the **Construct** link appears. Click it to configure OAuth authentication. +5. The Authorization window opens. Select the OAuth tab. + ![](assets/images/rest_test009.png) +6. In the **Type** group of options, select the **Signed Request** option. +7. In the **signature method** group of options, select which method will be used for signatures (HMAC-SHA1 or PLAINTEXT). +8. Fill in the following data: + ![](assets/images/rest_test010.png) + * **Consumer key**: Enter the **Key** value provided when you created the consumer in Magento Admin Panel. + * **Consumer secret**: Enter the **Secret** value provided when you created the consumer in Magento Admin Panel. + * **Access Token**: Enter the oauth\_token value received when you authenticated the application. + * **Access Token Secret**: Enter the oauth\_token\_secret value received when you authenticated the application. +9. Click **OK**. + **NOTE**: Advanced REST Client does not save the **Consumer secret** and **Access Token Secret** values. You need to enter these values each time you make a request. +10. In the **URL** field, enter the URL to which the API call will be performed and select the required HTTP method. +11. In the **Headers** table, click **Add row** and add the Accept - application/json or Accept - text/xml header depending on which format you prefer for the returned data. +12. Click **Send Request**. + +**Example: Retrieving the list of customers** + +1. In the **Method** group of options, select the **GET** option. +2. In the URL field, enter the following URL: https://om.ddev.site/api/rest/customers. +3. Click **Send request**. Information about all customers will be displayed in the response body. Note that only Admin type of the user can retrieve the list of customers. Example is as follows: + ![](assets/images/rest_test011.png) + +**Example: Creating a customer address** + +1. In the **Method** group of options, select the **POST** option. +2. In the URL field, enter the following URL: https://om.ddev.site/api/rest/customers/:id/addresses where the ":id" value is the customer ID in the system. +3. In the **Body** table, on the **Raw input** tab, enter the data required for customer address creation. +4. Click **Send request**. If the address is created, the 200 OK HTTP status code will be returned. Example is as follows: + ![](assets/images/rest_test012.png) \ No newline at end of file diff --git a/docs_includes/abbreviations.md b/docs_includes/abbreviations.md index 66298be132a..f4f6d9c25e2 100644 --- a/docs_includes/abbreviations.md +++ b/docs_includes/abbreviations.md @@ -4,6 +4,7 @@ *[deprecated]: Marked as not recommended for users and developers *[HTML]: Hyper Text Markup Language *[HTML5]: Hyper Text Markup Language +*[JSON]: JSON (JavaScript Object Notation) is a lightweight data-interchange format. *[Mailpit]: Mailpit is a small, fast, low memory, zero-dependency, multi-platform email testing tool & API for developers. *[n98-magerun]: The n98 magerun cli tools provides some handy tools to work with Magento from command line. *[OpenMage]: This project @@ -11,3 +12,4 @@ *[PhpStorm]: PhpStorm is an innovative, Java-based integrated development environment (IDE) engineered by JetBrains for PHP and web developers. *[TinyMCE]: WYSIWYG editor *[W3C]: World Wide Web Consortium +*[XML]: Extensible Markup Language diff --git a/mkdocs.yml b/mkdocs.yml index f0b931e591b..8e261fab9ec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,174 +7,186 @@ edit_uri: blob/main/docs/content copyright: OpenMage contributors site_author: OpenMage contributors site_description: >- - Magento - Long Term Support. + Magento - Long Term Support. docs_dir: docs/content # Configuration theme: - name: material - favicon: assets/images/favicon.ico - custom_dir: docs/overrides - palette: - - scheme: default - primary: white - accent: deep purple - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - scheme: slate - primary: black - accent: deep purple - toggle: - icon: material/brightness-4 - name: Switch to light mode - features: - - content.action.edit - - content.action.view - - content.code.copy - - navigation.expand - - navigation.indexes - - navigation.instant - - navigation.sections - - navigation.tabs - - navigation.top - - navigation.tracking + name: material + favicon: assets/images/favicon.ico + custom_dir: docs/overrides + palette: + - scheme: default + primary: white + accent: deep purple + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: black + accent: deep purple + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - content.action.edit + - content.action.view + - content.code.copy + - navigation.expand + - navigation.indexes + - navigation.instant + - navigation.sections + - navigation.tabs + - navigation.top + - navigation.tracking + icon: icon: - icon: - annotation: material/plus-circle - tag: - code: fontawesome/solid/code - config: fontawesome/solid/clipboard-check - css: fontawesome/brands/css3 - debug: fontawesome/solid/bug-slash - documentation: fontawesome/regular/file - events: fontawesome/regular/calendar-xmark - html: fontawesome/brands/html5 - install: fontawesome/solid/plus - js: fontawesome/brands/js - modules: fontawesome/regular/square-plus - php: fontawesome/brands/php - security: fontawesome/solid/shield - share: fontawesome/solid/share - tinymce: fontawesome/solid/wand-magic-sparkles + annotation: material/plus-circle + tag: + code: fontawesome/solid/code + config: fontawesome/solid/clipboard-check + css: fontawesome/brands/css3 + debug: fontawesome/solid/bug-slash + documentation: fontawesome/regular/file + events: fontawesome/regular/calendar-xmark + html: fontawesome/brands/html5 + install: fontawesome/solid/plus + js: fontawesome/brands/js + modules: fontawesome/regular/square-plus + php: fontawesome/brands/php + security: fontawesome/solid/shield + share: fontawesome/solid/share + tinymce: fontawesome/solid/wand-magic-sparkles # Plugins plugins: - - blog - - search - - tags: - tags_file: tags.md - - redirects: - redirect_maps: - - minify: - minify_html: true - cache_safe: true + - blog + - search + - tags: + tags_file: tags.md + - redirects: + redirect_maps: + - minify: + minify_html: true + cache_safe: true # Customization extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/OpenMage/magento-lts - - icon: fontawesome/brands/discord - link: https://discord.gg/EV8aNbU - - icon: fontawesome/brands/stack-overflow - link: https://magento.stackexchange.com/tags/openmage - - icon: fontawesome/brands/twitter - link: https://twitter.com/openmageproject - generator: false - tags: - Configuration: config - Contribute: share - CSS: css - Debug: debug - Development: code - Documentation: documentation - Events: events - HTML5: html - Install: install - JavaScript: js - Modules: modules - PHP-8.0: php - PHP-8.1: php - PHP-8.2: php - PHP-8.3: php - TinyMCE: tinymce - Security: security + social: + - icon: fontawesome/brands/github + link: https://github.com/OpenMage/magento-lts + - icon: fontawesome/brands/discord + link: https://discord.gg/EV8aNbU + - icon: fontawesome/brands/stack-overflow + link: https://magento.stackexchange.com/tags/openmage + - icon: fontawesome/brands/twitter + link: https://twitter.com/openmageproject + generator: false + tags: + Configuration: config + Contribute: share + CSS: css + Debug: debug + Development: code + Documentation: documentation + Events: events + HTML5: html + Install: install + JavaScript: js + Modules: modules + PHP-8.0: php + PHP-8.1: php + PHP-8.2: php + PHP-8.3: php + TinyMCE: tinymce + Security: security # Extensions markdown_extensions: - - abbr - - admonition - - attr_list - - def_list - - footnotes - - meta - - md_in_html - - toc: - permalink: true - toc_depth: 2 - - pymdownx.arithmatex: - generic: true - - pymdownx.betterem: - smart_enable: all - - pymdownx.caret - - pymdownx.details - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.inlinehilite - - pymdownx.keys - - pymdownx.magiclink: - repo_url_shorthand: true - user: OpenMage - repo: magento-lts - - pymdownx.mark - - pymdownx.smartsymbols - - pymdownx.snippets: - auto_append: - - docs_includes/abbreviations.md - - pymdownx.superfences: - - pymdownx.tabbed: - alternate_style: true - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tilde - - smarty + - abbr + - admonition + - attr_list + - def_list + - footnotes + - meta + - md_in_html + - toc: + permalink: true + toc_depth: 3 + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: OpenMage + repo: magento-lts + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.snippets: + auto_append: + - docs_includes/abbreviations.md + - pymdownx.superfences: + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - smarty nav: - - 'Get started': - - index.md - - users/requirements.md - - 'Installing': - - users/install/index.md - - users/install/_use-composer.md - - users/install/_use-git.md - - users/install/_use-tarball.md - - users/install/secure-install.md - - 'Changelog': - - developers/changelog/index.md - - developers/changelog/new-config.md - - developers/changelog/new-events.md - - developers/changelog/soap-wsdl.md - - 'Versioning': - - users/versioning/index.md - - users/versioning/maintained.md - - 'Quick links': - - tags.md - - 'Development': - - 'Events': - - developers/events/observer.md - - developers/events/list.md - - 'Tools': - - developers/ddev.md - - developers/phpstorm.md - - 'Multistore': - - developers/error-pages.md - - 'Documentation': - - developers/mkdocs.md - - 'Modules': - - users/modules/index.md - - users/modules/_payment.md - - users/modules/_themes.md - - users/modules/more.md + - 'Get started': + - index.md + - users/requirements.md + - 'Installing': + - users/install/index.md + - users/install/_use-composer.md + - users/install/_use-git.md + - users/install/_use-tarball.md + - users/install/secure-install.md + - 'Changelog': + - developers/changelog/index.md + - developers/changelog/new-config.md + - developers/changelog/new-events.md + - developers/changelog/soap-wsdl.md + - 'Versioning': + - users/versioning/index.md + - users/versioning/maintained.md + - 'Quick links': + - tags.md + - 'API': + - 'REST': + - api/rest/common_http_status_codes.md + - api/rest/http_methods.md + - api/rest/get_filters.md + - 'Resources': + - 'Products': + - api/rest/resources/products/product_categories.md + - 'Customers': + - api/rest/resources/customers.md + - api/rest/response_formats.md + - api/rest/testing_rest_resources.md + - 'Development': + - 'Events': + - developers/events/observer.md + - developers/events/list.md + - 'Tools': + - developers/ddev.md + - developers/phpstorm.md + - 'Multistore': + - developers/error-pages.md + - 'Documentation': + - developers/mkdocs.md + - 'Modules': + - users/modules/index.md + - users/modules/_payment.md + - users/modules/_themes.md + - users/modules/more.md # - 'Blog': # - blog/index.md