Documentation v4 📝 - github.io page

.gitattributes

@@ -3,6 +3,7 @@
 /.github export-ignore
 /dev export-ignore
 /docs export-ignore
+/docs_includes export-ignore
 /tests export-ignore
 
 /.all-contributorsrc export-ignore

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: MkDocs
+
+on:
+  workflow_call:
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+  push:
+    branches:
+      - main
+      - documentation
+    paths:
+      - 'docs/**.md'
+      - 'docs/**.html'
+      - 'docs/**.yml'
+      - 'docs_includes/**.md'
+      - 'mkdocs.yml'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip3 install mkdocs mkdocs-material mkdocs-minify-plugin mkdocs-redirects
+
+      - name: Publish docs
+        run: mkdocs gh-deploy --force

.gitignore

@@ -84,6 +84,9 @@ phpunit.xml
 /shell/update-copyright.php
 /shell/translations.php
 
+# generated by mkdocs serve
+/site
+
 # DDEV
 .ddev/config.yaml
 .ddev/.sampleData

docs/.htaccess

@@ -0,0 +1,2 @@
+Order deny,allow
+Deny from all

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.<br>Resource data invalid.<br>The request data is invalid.<br>Resource collection paging error.<br>The paging limit exceeds the allowed number.<br>Resource collection ordering error.<br>Resource collection filtering error.<br>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.<br>Resource method not implemented yet.                                                                                                                                                                                                                                                       |  
+| 500 Internal Error     | Unhandled simple errors.<br>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
+<?xml version="1.0"?>
+<magento_api>
+    <messages>
+        <error>
+            <data_item>
+                <code>404</code>
+                <message>Resource not found.</message>
+            </data_item>
+        </error>
+    </messages>
+</magento_api>
+```
+
+An error in the JSON format might look like the following:
+
+```json
+{"messages":{"error":[{"code":404,"message":"Resource not found."}]}}
+```

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][email protected]
+    ```

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.