[unchecked revision] | [checked revision] |
(→Reseller collection retrieval response message body) |
(→Reseller creation response message) |
||
(94 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
+ | Also visit [[stoney core: Resellers Resource Mapping (REST - LDAP)]]. | ||
+ | |||
= Overview = | = 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. | 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: | Basically, we want to be able to do the following things: | ||
− | * Create a new reseller (POST). | + | * Create a new reseller ([[#Reseller_creation_.28POST.29|POST]]). |
− | * Retrieve multiple resellers in the form of a list (GET). | + | * Retrieve multiple resellers in the form of a list ([[#Reseller_collection_retrieval_.28GET.29|GET]]). |
− | * Retrieve a single reseller (GET). | + | * Retrieve a single reseller ([[#Reseller_element_retrieval_.28GET.29|GET]]). |
− | * Update an existing reseller (PUT). | + | * Update an existing reseller ([[#Reseller_update_.28PUT.29|PUT]]). |
− | * Update | + | * Update one or more values of an existing reseller ([[#Reseller_partly_update_.28PATCH.29|PATCH]]). |
− | * Delete a single reseller (DELETE). | + | * 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. | 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. | ||
Line 14: | Line 16: | ||
= Resellers resource methods = | = Resellers resource methods = | ||
== Reseller creation (POST) == | == 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 | + | 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 information. |
− | 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 | + | 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 information about the new reseller. |
=== Reseller creation request message === | === Reseller creation request message === | ||
Line 39: | Line 41: | ||
| <pre> | | <pre> | ||
Accept: <Type>/<Subtype> | Accept: <Type>/<Subtype> | ||
− | Content-Type: <Type>/<Subtype> | + | Accept-Charset: <Charset> |
+ | Content-Type: <Type>/<Subtype>; charset=<Charset> | ||
</pre> | </pre> | ||
| <pre> | | <pre> | ||
Accept: application/json | Accept: application/json | ||
− | Content-Type: application/json | + | Accept-Charset: UTF-8 |
+ | Content-Type: application/json; charset=UTF-8 | ||
</pre> | </pre> | ||
Line 49: | Line 53: | ||
| [[#Reseller_creation_request_message_body|Request body]] | | [[#Reseller_creation_request_message_body|Request body]] | ||
| JSON object | | JSON object | ||
− | | < | + | | <source lang="javascript">{ ... }</source> |
|} | |} | ||
Line 90: | Line 94: | ||
|string | |string | ||
|yes | |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]] | + | |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]]. |
− | | | + | |UTF-8 {64} |
| | | | ||
| | | | ||
− | |<source lang="javascript">"resellerName": " | + | |<source lang="javascript">"resellerName": "Reseller Ltd."</source> |
|- | |- | ||
Line 100: | Line 104: | ||
|object | |object | ||
|yes | |yes | ||
− | |An object holding the billing address | + | |An object holding the billing address information for the given reseller. Refer to the [[#billingAddress_object|billingAddress object table]] for more information. |
| | | | ||
| | | | ||
Line 113: | Line 117: | ||
"postalAddress": "Street Number", | "postalAddress": "Street Number", | ||
"countryCode": "CH", | "countryCode": "CH", | ||
− | "postalCode": " | + | "postalCode": "1234", |
"localityName": "Locality", | "localityName": "Locality", | ||
"preferredLanguage": "en-GB", | "preferredLanguage": "en-GB", | ||
Line 127: | Line 131: | ||
|object | |object | ||
|no | |no | ||
− | |An object holding the shipping address | + | |An object holding the shipping address information for the given reseller. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more information. |
| | | | ||
| | | | ||
Line 140: | Line 144: | ||
"postalAddress": "Street Number", | "postalAddress": "Street Number", | ||
"countryCode": "CH", | "countryCode": "CH", | ||
− | "postalCode": " | + | "postalCode": "1234", |
"localityName": "Locality", | "localityName": "Locality", | ||
"preferredLanguage": "en-GB", | "preferredLanguage": "en-GB", | ||
Line 189: | Line 193: | ||
|yes | |yes | ||
|The given name (first name or forename) of the address holder. | |The given name (first name or forename) of the address holder. | ||
− | | | + | |UTF-8 {64} |
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
Line 199: | Line 203: | ||
|yes | |yes | ||
|The surname (last name or family name) of the address holder. | |The surname (last name or family name) of the address holder. | ||
− | | | + | |UTF-8 {64} |
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
Line 443: | Line 447: | ||
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
− | ! | + | ! HTTP response part |
! Content | ! Content | ||
! Example | ! Example | ||
|- | |- | ||
− | | | + | | Status Line |
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | | <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | ||
| <pre>HTTP/1.1 201 Created</pre> | | <pre>HTTP/1.1 201 Created</pre> | ||
Line 459: | Line 463: | ||
</pre> | </pre> | ||
|<pre> | |<pre> | ||
− | + | Content-Type: application/json; charset=UTF-8 | |
Location: https://api.example.com/v1/resellers/4000001 | Location: https://api.example.com/v1/resellers/4000001 | ||
</pre> | </pre> | ||
Line 466: | Line 470: | ||
| [[#Reseller_creation_response_message_body|Response body]] | | [[#Reseller_creation_response_message_body|Response body]] | ||
| JSON object | | JSON object | ||
− | | < | + | | <source lang="javascript">{ ... }</source> |
|} | |} | ||
Line 491: | Line 495: | ||
|@TODO add regex | |@TODO add regex | ||
| | | | ||
− | |< | + | |<source lang="javascript">"id": 4000001</source> |
|- | |- | ||
Line 498: | Line 502: | ||
|yes | |yes | ||
|The location URI of the newly created reseller resource, corresponds with the HTTP location header. | |The location URI of the newly created reseller resource, corresponds with the HTTP location header. | ||
− | |@TODO add link to URI RFC | + | |@TODO add link to URI RFC |
| | | | ||
| | | | ||
− | |< | + | |<source lang="javascript">"location": "https://api.example.com/v1/resellers/4000001"</source> |
|- | |- | ||
Line 507: | Line 511: | ||
|object | |object | ||
|no | |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 | + | |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 information. |
| | | | ||
| | | | ||
| | | | ||
− | |<source lang="javascript">error { /* ... */ }</source> | + | |<source lang="javascript">"error": { /* ... */ }</source> |
|} | |} | ||
Line 520: | Line 524: | ||
The service responds with a HTTP status code 200 (OK) on success and returns the various resellers. | 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 | + | 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 information. |
+ | |||
+ | ==== 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 ==== | ==== Reseller collection retrieval request message ==== | ||
Line 544: | Line 557: | ||
| <pre> | | <pre> | ||
Accept: <Type>/<Subtype> | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
</pre> | </pre> | ||
| <pre> | | <pre> | ||
Accept: application/json | Accept: application/json | ||
+ | Accept-Charset: UTF-8 | ||
</pre> | </pre> | ||
Line 559: | Line 574: | ||
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
− | ! | + | ! HTTP response part |
! Content | ! Content | ||
! Example | ! Example | ||
|- | |- | ||
− | | | + | | Status Line |
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | | <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | ||
− | | <pre>HTTP/1.1 | + | | <pre>HTTP/1.1 200 OK</pre> |
|- | |- | ||
Line 588: | Line 603: | ||
| [[#reseller_collection_retrieval_response_object|Response body]] | | [[#reseller_collection_retrieval_response_object|Response body]] | ||
| JSON object | | JSON object | ||
− | | < | + | | <source lang="javascript">{ ... }</source> |
|} | |} | ||
Line 621: | Line 636: | ||
"isCompany": true, | "isCompany": true, | ||
"isActive": true, | "isActive": true, | ||
− | "resellerName": "Reseller Ltd" | + | "resellerName": "Reseller Ltd." |
+ | "countryCode": "CH", | ||
+ | "postalCode": "3012", | ||
+ | "localityName": "Bern" | ||
}, | }, | ||
{ | { | ||
Line 633: | Line 651: | ||
|object | |object | ||
|no | |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 | + | |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 information. |
| | | | ||
| | | | ||
Line 663: | Line 681: | ||
|@TODO add regex | |@TODO add regex | ||
| | | | ||
− | |< | + | |<source lang="javascript">"id": 4000000</source> |
|- | |- | ||
Line 673: | Line 691: | ||
| | | | ||
| | | | ||
− | |< | + | |<source lang="javascript">"location": "https://api.example.com/v1/resellers/4000000"</source> |
|- | |- | ||
Line 699: | Line 717: | ||
|string | |string | ||
|yes | |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]] | + | |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]]. |
| | | | ||
| | | | ||
| | | | ||
− | |<source lang="javascript">"resellerName": " | + | |<source lang="javascript">"resellerName": "Reseller Ltd."</source> |
+ | |||
+ | |- | ||
+ | |<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) === | === Reseller element retrieval (GET) === | ||
− | To retrieve an existing reseller and fetch the | + | To retrieve an existing reseller and fetch the 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 | + | The service responds with a HTTP status code 200 (OK) on success and returns the associated reseller information. |
==== Reseller element retrieval request message ==== | ==== Reseller element retrieval request message ==== | ||
Line 733: | Line 781: | ||
| <pre> | | <pre> | ||
Accept: <Type>/<Subtype> | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
</pre> | </pre> | ||
| <pre> | | <pre> | ||
Accept: application/json | Accept: application/json | ||
+ | Accept-Charset: UTF-8 | ||
</pre> | </pre> | ||
Line 744: | Line 794: | ||
|} | |} | ||
− | |||
==== Reseller element retrieval response message ==== | ==== Reseller element retrieval response message ==== | ||
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
− | ! | + | ! HTTP response part |
! Content | ! Content | ||
! Example | ! Example | ||
|- | |- | ||
− | | | + | | Status Line |
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | | <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre> | ||
− | | <pre>HTTP/1.1 | + | | <pre>HTTP/1.1 200 OK</pre> |
|- | |- | ||
Line 770: | Line 819: | ||
|- | |- | ||
− | | [[# | + | | [[#Reseller_element_retrieval_response_message_body|Response body]] |
| JSON object | | JSON object | ||
− | | < | + | | <source lang="javascript">{ ... }</source> |
|} | |} | ||
====== Reseller element retrieval response message body ====== | ====== Reseller element retrieval response message body ====== | ||
− | {| class="wikitable sortable" style="width: 100%;" id=" | + | {| class="wikitable sortable" style="width: 100%;" id="reseller_element_retrival_response_object" |
|- | |- | ||
− | |+ align="top" style="text-align:left;"|Reseller | + | |+ align="top" style="text-align:left;"|Reseller Element Retrieval Response Object |
! Parameter name | ! Parameter name | ||
! Data type | ! Data type | ||
Line 788: | Line 837: | ||
! Default value | ! Default value | ||
! Example | ! Example | ||
+ | |||
+ | |- | ||
+ | |<code>id</code> | ||
+ | |integer | ||
+ | |yes | ||
+ | |The identification number of the reseller. | ||
+ | | | ||
+ | |@TODO add regex | ||
+ | | | ||
+ | |<source lang="javascript">"id": 4000001</source> | ||
+ | |||
+ | |- | ||
+ | |<code>isCompany</code> | ||
+ | |boolean | ||
+ | |yes | ||
+ | |<code>true</code> if the reseller represents a company, <code>false</code> if it's an individual person. | ||
+ | |<code>true</code> or <code>false</code> | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"isCompany": true</source> | ||
+ | |||
+ | |- | ||
+ | |<code>isActive</code> | ||
+ | |boolean | ||
+ | |yes | ||
+ | | | ||
+ | |<code>true</code> or <code>false</code> | ||
+ | | | ||
+ | |<code>true</code> | ||
+ | |<source lang="javascript">"isActive": true</source> | ||
+ | |||
+ | |- | ||
+ | |<code>resellerName</code> | ||
+ | |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]]. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"resellerName": "Reseller Ltd."</source> | ||
+ | |||
+ | |- | ||
+ | |[[#billingAddress_object|<code>billingAddress</code>]] | ||
+ | |object | ||
+ | |yes | ||
+ | |An object holding the billing address information for the given reseller. Refer to the [[#billingAddress_object|billingAddress object table]] for more information. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript"> | ||
+ | "billingAddress": | ||
+ | { | ||
+ | "organizationName": "Reseller Ltd.", | ||
+ | "gender": 'm', | ||
+ | "givenName": "Name", | ||
+ | "surname": "Surname", | ||
+ | "postalAddress": "Street Number", | ||
+ | "countryCode": "CH", | ||
+ | "postalCode": "1234", | ||
+ | "localityName": "Locality", | ||
+ | "preferredLanguage": "en-GB", | ||
+ | "mail": "name.surname@example.com", | ||
+ | "telephoneNumber": "+41 00 000 00 00", | ||
+ | "mobileTelephoneNumber": "+41 00 000 00 00", | ||
+ | "websiteURL": "https://www.example.com/" | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | |- | ||
+ | |[[#shippingAddress_object|<code>shippingAddress</code>]] | ||
+ | |object | ||
+ | |no | ||
+ | |An object holding the shipping address information for the given reseller. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more information. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript"> | ||
+ | "shippingAddress": | ||
+ | { | ||
+ | "organizationName": "Reseller Ltd.", | ||
+ | "gender": 'm', | ||
+ | "givenName": "Name", | ||
+ | "surname": "Surname", | ||
+ | "postalAddress": "Street Number", | ||
+ | "countryCode": "CH", | ||
+ | "postalCode": "1234", | ||
+ | "localityName": "Locality", | ||
+ | "preferredLanguage": "en-GB", | ||
+ | "mail": "name.surname@example.com", | ||
+ | "telephoneNumber": "+41 00 000 00 00", | ||
+ | "mobileTelephoneNumber": "+41 00 000 00 00", | ||
+ | "websiteURL": "https://www.example.com/" | ||
+ | } | ||
+ | </source> | ||
+ | |||
+ | |- | ||
+ | |<code>customers</code> | ||
+ | |string | ||
+ | |yes | ||
+ | |The location URI of the customers belonging to this reseller resource. | ||
+ | |@TODO add link to URI RFC | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"customers": "https://api.example.com/v1/resellers/4000001/customers"</source> | ||
+ | |||
+ | |- | ||
+ | |<code>employees</code> | ||
+ | |string | ||
+ | |yes | ||
+ | |The location URI of the employees belonging to this reseller resource. | ||
+ | |@TODO add link to URI RFC | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"employees": "https://api.example.com/v1/resellers/4000001/employees"</source> | ||
+ | |||
+ | |- | ||
+ | |<code>users</code> | ||
+ | |string | ||
+ | |yes | ||
+ | |The location URI of the users belonging to this reseller resource. | ||
+ | |@TODO add link to URI RFC | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"users": "https://api.example.com/v1/resellers/4000001/users"</source> | ||
+ | |||
+ | |- | ||
+ | |[[stoney_core:_REST_API#Error_codes_and_responses|<code>error</code>]] | ||
+ | |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 information. | ||
+ | | | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript">"error": { /* ... */ }</source> | ||
|} | |} | ||
Line 796: | Line 979: | ||
The <code>PUT</code> method requires one to sent the complete record, thus the work-flow is normally as follows: | The <code>PUT</code> method requires one to sent the complete record, thus the work-flow is normally as follows: | ||
− | # A [[# | + | # A [[#Reseller_element_retrieval_.28GET.29|GET]] request on the Reseller element URI will be made to fetch the whole document. |
# Update the fields which content has changed | # Update the fields which content has changed | ||
# Send a <code>PUT</code> request with all the reseller data | # Send a <code>PUT</code> request with all the reseller data | ||
+ | |||
+ | === Reseller update request message === | ||
+ | {| class="wikitable sortable" style="width: 100%;" | ||
+ | |- | ||
+ | ! HTTP request part | ||
+ | ! Content | ||
+ | ! Example | ||
+ | |||
+ | |- | ||
+ | | Request lines | ||
+ | |<pre> | ||
+ | PUT <Request-URI> HTTP 1.1 | ||
+ | HOST: <Host> | ||
+ | </pre> | ||
+ | |<pre> | ||
+ | PUT /v1/resellers/4000001 HTTP 1.1 | ||
+ | HOST: api.example.com | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | Request headers | ||
+ | | <pre> | ||
+ | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
+ | Content-Type: <Type>/<Subtype>; charset=<Charset> | ||
+ | </pre> | ||
+ | | <pre> | ||
+ | Accept: application/json | ||
+ | Accept-Charset: UTF-8 | ||
+ | Content-Type: application/json; charset=UTF-8 | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | [[#Reseller_update_request_message_body|Request body]] | ||
+ | | JSON object | ||
+ | | <source lang="javascript">{ ... }</source> | ||
+ | |||
+ | |} | ||
+ | |||
+ | ==== Reseller update request message body ==== | ||
+ | See [[#reseller_object|Reseller object]]. | ||
+ | |||
+ | === Reseller 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_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) == | == Reseller partly update (PATCH) == | ||
Line 805: | Line 1,060: | ||
In contrast to the [[#Reseller_update_.28PUT.29|<code>PUT</code>]] method, only the changed fields are to be included in the request. | 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%;" | ||
+ | |- | ||
+ | ! HTTP request part | ||
+ | ! Content | ||
+ | ! Example | ||
+ | |||
+ | |- | ||
+ | | Request lines | ||
+ | |<pre> | ||
+ | PATCH <Request-URI> HTTP 1.1 | ||
+ | HOST: <Host> | ||
+ | </pre> | ||
+ | |<pre> | ||
+ | PATCH /v1/resellers/4000001 HTTP 1.1 | ||
+ | HOST: api.example.com | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | Request headers | ||
+ | | <pre> | ||
+ | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
+ | Content-Type: <Type>/<Subtype>; charset=<Charset> | ||
+ | </pre> | ||
+ | | <pre> | ||
+ | Accept: application/json | ||
+ | Accept-Charset: UTF-8 | ||
+ | Content-Type: application/json; charset=UTF-8 | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | [[#Reseller_update_request_message_body|Request body]] | ||
+ | | JSON object | ||
+ | | <source lang="javascript">{ ... }</source> | ||
+ | |||
+ | |} | ||
+ | |||
+ | ==== Reseller partly update request message body ==== | ||
+ | The JSON message body consists out of one or more fields from the [[#reseller_object|Reseller object]]. | ||
+ | @TODO: Add example. | ||
+ | |||
+ | === 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_partly_update_response_message_body|Response body]] | ||
+ | | JSON object | ||
+ | | <source lang="javascript">{ ... }</source> | ||
+ | |||
+ | |} | ||
+ | |||
+ | ==== Reseller partly 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 deletion (DELETE) == | == Reseller deletion (DELETE) == | ||
− | To delete an existing reseller, the client needs to send a HTTP <code>DELETE</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 <code>200</code> (OK) on success and returns an empty body. | + | 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.1 | ||
+ | HOST: <Host> | ||
+ | </pre> | ||
+ | |<pre> | ||
+ | DELETE /v1/resellers/4000001 HTTP 1.1 | ||
+ | HOST: api.example.com | ||
+ | </pre> | ||
+ | |||
+ | |- | ||
+ | | Request headers | ||
+ | | <pre> | ||
+ | Accept: <Type>/<Subtype> | ||
+ | Accept-Charset: <Charset> | ||
+ | </pre> | ||
+ | | <pre> | ||
+ | Accept: application/json | ||
+ | Accept-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 = | = Links = | ||
+ | * [[stoney core: REST API]] | ||
− | [[Category:REST API]] | + | [[Category:REST API]][[Category:stoney core]] |
Latest revision as of 12:00, 5 August 2014
Also visit stoney core: Resellers Resource Mapping (REST - LDAP).
Overview
The REST API describes the (Representational State Transfer Application Programming Interface) of the resellers resource to be used by stoney core, stoney conductor and other Self-Service Modules or third party applications.
Basically, we want to be able to do the following things:
- Create a new reseller (POST).
- Retrieve multiple resellers in the form of a list (GET).
- Retrieve a single reseller (GET).
- Update an existing reseller (PUT).
- Update one or more values of an existing reseller (PATCH).
- Delete a single reseller (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 Mapping (REST - LDAP) category.
Resellers resource methods
Reseller creation (POST)
To create a new reseller the client needs to send a HTTP POST
request on the reseller collection resource URI https://api.example.com/v1/resellers
(also see Base URI), including the associated reseller information.
The service will generate a new reseller and responds with a HTTP status code 201
(Created) on success. The newly created reseller URI is returned within the HTTP location header, which can be used by the client to gather information about the new reseller.
Reseller creation request message
HTTP request part | Content | Example |
---|---|---|
Request lines | POST <Request-URI> HTTP 1.1 HOST: <Host> |
POST /v1/resellers/ HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Reseller creation request message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
isCompany
|
boolean | yes | true if the reseller represents a company, false if it's an individual person.
|
true or false
|
"isCompany": true | ||
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
resellerName
|
string | yes | The reseller's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object.
|
UTF-8 {64} | "resellerName": "Reseller Ltd." | ||
billingAddress
|
object | yes | An object holding the billing address information for the given reseller. Refer to the billingAddress object table for more information. | "billingAddress": { "organizationName": "Reseller Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/" } | |||
shippingAddress
|
object | no | An object holding the shipping address information for the given reseller. Refer to the shippingAddress object table for more information. | "shippingAddress": { "organizationName": "Reseller Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/" } |
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
organizationName
|
string | no | The name of the organization. | @TODO: Add regex | "organizationName": "Reseller Ltd." | ||
gender
|
string | yes | The gender of the address holder | Either f for female, m for male or n for neutral.
|
"gender": "f" | ||
givenName
|
string | yes | The given name (first name or forename) of the address holder. | UTF-8 {64} | @TODO: Add regex | "givenName": "Name" | |
surname
|
string | yes | The surname (last name or family name) of the address holder. | UTF-8 {64} | @TODO: Add regex | "surname": "Surname" | |
postalAddress
|
string | yes | @TODO: Add regex | "postalAddress": "" | |||
countryCode
|
string | yes | @TODO: Add regex | "countryCode": "" | |||
postalCode
|
string | yes | @TODO: Add regex | "postalCode": "" | |||
localityName
|
string | yes | @TODO: Add regex | "localityName": "" | |||
preferredLanguage
|
string | yes | @TODO: Add regex | "preferredLanguage": "" | |||
mail
|
string | yes | @TODO: Add regex | "mail": "" | |||
telephoneNumber
|
string | yes | @TODO: Add regex | "telephoneNumber": "" | |||
mobileTelephoneNumber
|
string | yes | @TODO: Add regex | "mobileTelephoneNumber": "" | |||
websiteURL
|
string | yes | @TODO: Add regex | "websiteURL": "" |
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
organizationName
|
string | no | The name of the organization. | @TODO: Add regex | "organizationName": "Reseller Ltd." | ||
gender
|
string | yes | The gender of the address holder | Either f for female, m for male or n for neutral.
|
"gender": "f" | ||
givenName
|
string | yes | The given name (first name or forename) of the address holder. | @TODO: Add regex | "givenName": "Name" | ||
surname
|
string | yes | The surname (last name or family name) of the address holder. | @TODO: Add regex | "surname": "Surname" | ||
postalAddress
|
string | yes | @TODO: Add regex | "postalAddress": "" | |||
countryCode
|
string | yes | @TODO: Add regex | "countryCode": "" | |||
postalCode
|
string | yes | @TODO: Add regex | "postalCode": "" | |||
localityName
|
string | yes | @TODO: Add regex | "localityName": "" | |||
preferredLanguage
|
string | yes | @TODO: Add regex | "preferredLanguage": "" | |||
mail
|
string | yes | @TODO: Add regex | "mail": "" | |||
telephoneNumber
|
string | yes | @TODO: Add regex | "telephoneNumber": "" | |||
mobileTelephoneNumber
|
string | yes | @TODO: Add regex | "mobileTelephoneNumber": "" | |||
websiteURL
|
string | yes | @TODO: Add regex | "websiteURL": "" |
Reseller creation response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 201 Created |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> |
Content-Type: application/json; charset=UTF-8 Location: https://api.example.com/v1/resellers/4000001 |
Response body | JSON object | { ... } |
Reseller creation response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the newly created reseller resource. | @TODO add regex | "id": 4000001 | ||
location
|
string | yes | The location URI of the newly created reseller resource, corresponds with the HTTP location header. | @TODO add link to URI RFC | "location": "https://api.example.com/v1/resellers/4000001" | ||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | "error": { /* ... */ } |
Reseller retrieval (GET)
Reseller collection retrieval (GET)
To retrieve existing resellers, the client needs to send a HTTP GET
request on the reseller's collection resource URI https://api.example.com/v1/resellers
.
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 Pagination chapter for more information.
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: https://api.example.com/v1/resellers?sort=resellerName,isActive
. For further information on filtering, sorting and searching, visit stoney core: REST API.
Search (fulltext)
To form a fulltext search (resellers only), append the url query parameter q with the desired search text: https://api.example.com/v1/resellers?q=example
. The document 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: https://api.example.com/v1/resellers?resellerName=example
. You're allowed to search for all attributes that are returned in the Reseller element retrieval response message body.
Reseller collection retrieval request message
HTTP request part | Content | Example |
---|---|---|
Request lines | GET <Request-URI> HTTP 1.1 HOST: <Host> |
GET /v1/resellers/ HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
Reseller collection retrieval response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> Link: X-Total-Count: |
Content-Type: Content-Type: application/json; charset=UTF-8 Link: <https://api.example.com/v1/resellers?page=1&per_page=30>; rel="first", <https://api.example.com/v1/resellers?page=2&per_page=30>; rel="prev", <https://api.example.com/v1/resellers?page=4&per_page=30>; rel="next", <https://api.example.com/v1/resellers?page=10&per_page=30>; rel="last" X-Total-Count: 295 |
Response body | JSON object | { ... } |
Reseller collection retrieval response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example
|
---|---|---|---|---|---|---|---|
array | no | An array with one or more reseller collection objects | [ { "id": 4000000, "location": "https://api.example.com/v1/resellers/4000000", "isCompany": true, "isActive": true, "resellerName": "Reseller Ltd." "countryCode": "CH", "postalCode": "3012", "localityName": "Bern" }, { /* ... */ } ] | ||||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | error { /* ... */ } |
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the reseller. | @TODO add regex | "id": 4000000 | ||
location
|
string | yes | The location URI of the reseller resource. | @TODO add link to URI RFC | "location": "https://api.example.com/v1/resellers/4000000" | ||
isCompany
|
boolean | yes | true if the reseller represents a company, false if it's an individual person.
|
true or false
|
"isCompany": true | ||
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
resellerName
|
string | yes | The reseller's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object.
|
"resellerName": "Reseller Ltd." | |||
countryCode
|
string | yes | @TODO: Add regex | "countryCode": "CH" | |||
postalCode
|
string | yes | @TODO: Add regex | "postalCode": "3012" | |||
localityName
|
string | yes | @TODO: Add regex | "localityName": "Bern |
Reseller element retrieval (GET)
To retrieve an existing reseller and fetch the information associated with it, the client needs to send a HTTP GET
request on the reseller's element resource URI (such as https://api.example.com/v1/resellers/4000001
.
The service responds with a HTTP status code 200 (OK) on success and returns the associated reseller information.
Reseller element retrieval request message
HTTP request part | Content | Example |
---|---|---|
Request lines | GET <Request-URI> HTTP 1.1 HOST: <Host> |
GET /v1/resellers/4000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
Reseller element retrieval response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> |
Content-Type: Content-Type: application/json; charset=UTF-8 Location: https://api.example.com/v1/resellers/4000001 |
Response body | JSON object | { ... } |
Reseller element retrieval response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the reseller. | @TODO add regex | "id": 4000001 | ||
isCompany
|
boolean | yes | true if the reseller represents a company, false if it's an individual person.
|
true or false
|
"isCompany": true | ||
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
resellerName
|
string | yes | The reseller's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object.
|
"resellerName": "Reseller Ltd." | |||
billingAddress
|
object | yes | An object holding the billing address information for the given reseller. Refer to the billingAddress object table for more information. | "billingAddress": { "organizationName": "Reseller Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/" } | |||
shippingAddress
|
object | no | An object holding the shipping address information for the given reseller. Refer to the shippingAddress object table for more information. | "shippingAddress": { "organizationName": "Reseller Ltd.", "gender": 'm', "givenName": "Name", "surname": "Surname", "postalAddress": "Street Number", "countryCode": "CH", "postalCode": "1234", "localityName": "Locality", "preferredLanguage": "en-GB", "mail": "name.surname@example.com", "telephoneNumber": "+41 00 000 00 00", "mobileTelephoneNumber": "+41 00 000 00 00", "websiteURL": "https://www.example.com/" } | |||
customers
|
string | yes | The location URI of the customers belonging to this reseller resource. | @TODO add link to URI RFC | "customers": "https://api.example.com/v1/resellers/4000001/customers" | ||
employees
|
string | yes | The location URI of the employees belonging to this reseller resource. | @TODO add link to URI RFC | "employees": "https://api.example.com/v1/resellers/4000001/employees" | ||
users
|
string | yes | The location URI of the users belonging to this reseller resource. | @TODO add link to URI RFC | "users": "https://api.example.com/v1/resellers/4000001/users" | ||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | "error": { /* ... */ } |
Reseller update (PUT)
To updates an existing reseller, the client needs to send a HTTP PUT
request on the reseller's element resource URI (such as, https://api.example.com/v1/resellers/4000001
).
The service responds with a HTTP status code 200 (OK) on success and returns an empty body.
The PUT
method requires one to sent the complete record, thus the work-flow is normally as follows:
- A GET request on the Reseller element URI will be made to fetch the whole document.
- Update the fields which content has changed
- Send a
PUT
request with all the reseller data
Reseller update request message
HTTP request part | Content | Example |
---|---|---|
Request lines | PUT <Request-URI> HTTP 1.1 HOST: <Host> |
PUT /v1/resellers/4000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Reseller update request message body
See Reseller object.
Reseller update response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Reseller update response message body
On success (200
) an empty response message body will be returned, otherwise an 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 PATCH
request on the reseller's element resource URI (such as, https://api.example.com/v1/resellers/4000001
).
The service responds with a HTTP status code 200 (OK) on success and returns an empty body.
In contrast to the PUT
method, only the changed fields are to be included in the request.
Reseller partly update request message
HTTP request part | Content | Example |
---|---|---|
Request lines | PATCH <Request-URI> HTTP 1.1 HOST: <Host> |
PATCH /v1/resellers/4000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Reseller partly update request message body
The JSON message body consists out of one or more fields from the Reseller object. @TODO: Add example.
Reseller partly update response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Reseller partly update response message body
On success (200
) an empty response message body will be returned, otherwise an error object will provide further information about the failure.
Reseller deletion (DELETE)
To delete an existing reseller, the client needs to send a HTTP DELETE
request, with an empty request body on the reseller's element resource URI (such as, https://api.example.com/v1/resellers/4000001
). The service responds with a HTTP status code 200
(OK) on success and returns an empty body.
Reseller deletion request message
HTTP request part | Content | Example |
---|---|---|
Request lines | DELETE <Request-URI> HTTP 1.1 HOST: <Host> |
DELETE /v1/resellers/4000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
Reseller deletion response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Reseller deletion response message body
On success (200
) an empty response message body will be returned, otherwise an 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.