Also visit [[stoney core: Resellers Resource Mapping (REST - LDAP)]].
= Overview =
The REST API describes the ('''Re'''presentational '''S'''tate '''T'''ransfer '''A'''pplication '''P'''rogramming '''I'''nterface) of the resellers resource to be used by [[:Category:stoney core|stoney core]], [[:Category:stoney conductor|stoney conductor]] and other [[:Category:Self-Service Modules|Self-Service Modules]] or third party applications.
Basically, we want to be able to do the following things:
* Create a new reseller ([[#Reseller_creation_.28POST.29|POST]]).* Retrieve multiple resellers in the form of a list ([[#Reseller_collection_retrieval_.28GET.29|GET]]).* Retrieve a single reseller ([[#Reseller_element_retrieval_.28GET.29|GET]]).* Update an existing reseller ([[#Reseller_update_.28PUT.29|PUT]]).* Update a single value one or more values of an existing reseller ([[#Reseller_partly_update_.28PATCH.29|PATCH]]).* Delete a single reseller ([[#Reseller_deletion_.28DELETE.29|DELETE]]).
To get an idea what happens behind the screens, have a look at the [[stoney core: Resellers Resource Mapping (REST - LDAP)]] documentation located in the [[:Category:Mapping (REST - LDAP)|Mapping (REST - LDAP)]] category.
= Resellers resource methods =
== Reseller creation (POST) ==
To create a new reseller the client needs to send a HTTP <code>POST</code> request on the reseller collection resource URI <code>https://api.example.com/v1/resellers</code> (also see [[Application_Programming_Interface_(API)#Base_URI|Base URI]]), including the associated reseller informationsinformation.The service will generate a new reseller and responds with a HTTP status code <code>201</code> (Created) on success. The newly created reseller URI is returned within the HTTP location header, which can be used by the client to gather informations information about the new reseller.
=== Reseller creation request message ===
| [[#Reseller_creation_request_message_body|Request body]]
| JSON object
| <presource lang="javascript">{ ... }</presource>
|}
|string
|yes
|The reseller's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.|UTF-8 {64}
|
|
|<source lang="javascript">"resellerName": "Super-duper HostingReseller Ltd."</source>
|-
|object
|yes
|An object holding the billing address informations information for the given reseller. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
|object
|no
|An object holding the shipping address informations information for the given reseller. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
|yes
|The given name (first name or forename) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|yes
|The surname (last name or family name) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/resellers/4000001
</pre>
| [[#Reseller_creation_response_message_body|Response body]]
| JSON object
| <presource lang="javascript">{ ... }</presource>
|}
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
The service responds with a HTTP status code 200 (OK) on success and returns the various resellers.
Note that the service will only return a limited amount of objects at once and provides links for retrieving further objects. Refer to the [[stoney_core:_REST_API#Pagination|Pagination chapter]] for more informationsinformation. ==== Sort ====If you don't add a sort attribute, the collection will be sorted by '''id''' (ascending). If you would like a sorted collection answer, the query parameter sort must be added with the object's sort attribute(s) as the value: <code>https://api.example.com/v1/resellers?sort=resellerName,isActive</code>. For further information on filtering, sorting and searching, visit [[stoney_core:_REST_API#Filtering.2C_sorting_and_searching | stoney core: REST API]]. ==== Search (fulltext) ====To form a fulltext search (resellers only), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/resellers?q=example</code>. The document [[stoney_core:_Search_Resource_-_REST_API#Resellers_Search_.28GET.29 | stoney core: Search Resource - REST API]] describes the search in detail. ==== Search (with filter) ====To form a specific search, append the url query attribute(s) name (for example '''resellerName''') with the desired search text: <code>https://api.example.com/v1/resellers?resellerName=example</code>. You're allowed to search for all attributes that are returned in the [[#Reseller_element_retrieval_response_message_body | Reseller element retrieval response message body]].
==== Reseller collection retrieval request message ====
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 201 Created200 OK</pre>
|-
| [[#reseller_collection_retrieval_response_object|Response body]]
| JSON object
| <presource lang="javascript">{ ... }</presource>
|}
"isCompany": true,
"isActive": true,
"resellerName": "Reseller Ltd." "countryCode": "CH", "postalCode": "3012", "localityName": "Bern"
},
{
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
|string
|yes
|The reseller's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"resellerName": "SuperReseller Ltd."</source> |-duper Hosting|<code>countryCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"countryCode": "CH"</source> |-|<code>postalCode</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"postalCode": "3012"</source> |-|<code>localityName</code>|string|yes|||@TODO: Add regex||<source lang="javascript">"localityName": "Bern</source>
|}
=== Reseller element retrieval (GET) ===
To retrieve an existing reseller and fetch the informations information associated with it, the client needs to send a HTTP <code>GET</code> request on the reseller's element resource URI (such as <code>https://api.example.com/v1/resellers/4000001</code>.The service responds with a HTTP status code 200 (OK) on success and returns the associated reseller informationsinformation.
==== Reseller element retrieval request message ====
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 201 Created200 OK</pre>
|-
|string
|yes
|The reseller's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"resellerName": "Super-duper HostingReseller Ltd."</source>
|-
|object
|yes
|An object holding the billing address informations information for the given reseller. Refer to the [[#billingAddress_object|billingAddress object table]] for more informationsinformation.
|
|
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
|object
|no
|An object holding the shipping address informations information for the given reseller. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informationsinformation.
|
|
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
|
|
|<source lang="javascript">"locationcustomers": "https://api.example.com/v1/resellers/4000001/customers"</source>
|-
|
|
|<source lang="javascript">"locationemployees": "https://api.example.com/v1/resellers/4000001/employees"</source>
|-
|
|
|<source lang="javascript">"locationusers": "https://api.example.com/v1/resellers/4000001/users"</source>
|-
|object
|no
|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informationsinformation.
|
|
</pre>
|<pre>
POST PUT /v1/resellers/4000001 HTTP 1.1
HOST: api.example.com
</pre>
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
Location: <Location-URI>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/resellers/4000001
</pre>
|-
| [[#Reseller_creation_response_message_bodyReseller_update_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
==== Reseller update response message body ====
On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further information about the failure. == Reseller partly update (PATCH) ==To update fields of an existing reseller, the client needs to send a HTTP <code>PATCH</code> request on the reseller's element resource URI (such as, <code>https://api.example.com/v1/resellers/4000001</code>).The service responds with a HTTP status code 200 (OK) on success and returns an empty body. In contrast to the [[#Reseller_update_.28PUT.29|<code>PUT</code>]] method, only the changed fields are to be included in the request. === Reseller partly update request message ==={| class="wikitable sortable" style="width: 100%;" id="reseller_creation_response_object"
|-
|+ align="top" style="text-align:left;"|Reseller Creation Response Object! Parameter name! Data type! Mandatory! Description! Valid content![http://www.pcre.org/ PCRE]HTTP request part! Default valueContent
! Example
|-
| Request lines|<codepre>idPATCH </codeRequest-URI>|integer|yes|The identification number of the newly created reseller resourceHTTP 1.1|HOST: <Host>|@TODO add regex|</pre>|<source lang="javascript"pre>"id": PATCH /v1/resellers/4000001HTTP 1.1HOST: api.example.com</sourcepre>
|-
| Request headers|<codepre>locationAccept: <Type>/code<Subtype>|stringAccept-Charset: <Charset>|yesContent-Type: <Type>/<Subtype>; charset=<Charset>|The location URI of the newly created reseller resource, corresponds with the HTTP location header.|@TODO add link to URI RFC||</pre>|<source lang="javascript"pre>"location": "httpsAccept:application/jsonAccept-Charset: UTF-8Content-Type: application/api.example.com/v1/resellers/4000001"json; charset=UTF-8</sourcepre>
|-
|[[stoney_core:_REST_API#Error_codes_and_responsesReseller_update_request_message_body|<code>error</code>Request body]]|JSON object|no|In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more informations.||||<source lang="javascript">"error": { /* ... */ }</source>
|}
==== Reseller partly update (PATCH) request message body ====To update fields The JSON message body consists out of an existing reseller, one or more fields from the client needs to send a HTTP <code>PATCH</code> request on the reseller's element resource URI (such as, <code>https://api.example.com/v1/resellers/4000001</code>)[[#reseller_object|Reseller object]].The service responds with a HTTP status code 200 (OK) on success and returns an empty body@TODO: Add example.
In contrast to the === Reseller partly update response message ==={| class="wikitable sortable" style="width: 100%;"|-! HTTP response part! Content! Example |-| Status Line| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>| <pre>HTTP/1.1 200 OK</pre> |-| Response headers|<pre>Content-Type: <Type>/<Subtype>; charset=<Charset></pre>|<pre>Content-Type: Content-Type: application/json; charset=UTF-8</pre> |-| [[#Reseller_update_Reseller_partly_update_response_message_body|Response body]]| JSON object| <source lang="javascript">{ .28PUT.29. }</source> |} ==== Reseller partly update response message body ====On success (<code>PUT200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] method, only the changed fields are to be included in will provide further information about the requestfailure.
== Reseller deletion (DELETE) ==
To delete an existing reseller, the client needs to send a HTTP <code>DELETE</code> request , with an empty request body on the reseller's element resource URI (such as, <code>https://api.example.com/v1/resellers/4000001</code>). The service responds with a HTTP status code <code>200</code> (OK) on success and returns an empty body. === Reseller deletion request message ==={| class="wikitable sortable" style="width: 100%;"|-! HTTP request part! Content! Example |-| Request lines|<pre>DELETE <Request-URI> HTTP 1.1HOST: <Host></pre>|<pre>DELETE /v1/resellers/4000001 HTTP 1.1HOST: api.example.com</pre> |-| Request headers| <pre>Accept: <Type>/<Subtype>Accept-Charset: <Charset></pre>| <pre>Accept: application/jsonAccept-Charset: UTF-8</pre> |-| Request body| <Empty>| <pre></pre> |} === Reseller deletion response message ==={| class="wikitable sortable" style="width: 100%;"|-! HTTP response part! Content! Example |-| Status Line| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>| <pre>HTTP/1.1 200 OK</pre> |-| Response headers|<pre>Content-Type: <Type>/<Subtype>; charset=<Charset></pre>|<pre>Content-Type: Content-Type: application/json; charset=UTF-8</pre> |-| [[#Reseller_partly_update_response_message_body|Response body]]| JSON object| <source lang="javascript">{ ... }</source> |} ==== Reseller deletion response message body ====On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further information about the failure. == Reseller search ==The reseller search is a sub section of the [[stoney core: Search Resource - REST API]] and is described there in more detail.
= Links =
* [[stoney core: REST API]]
[[Category:REST API]][[Category:stoney core]]