* Nested URLs vs. filter via get parameter => <code>/users/<UID>/products</code> vs. <code>/products/?userId=<UID></code>, (choose a better word for product?)
* Sudo mechanism, via custom HTTP header, for example <code>X-USER</code>
=== Reseller resource ===
Resource representing a collection of resellers or a specific reseller element.
==== 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>, including the associated reseller informations.
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 about the new reseller.
TBD: Table of all attributes (including optional ones)
===== Reseller creation (POST) example =====
'''Request''':
<pre>
POST /v1/resellers/ HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
Content-Type: application/json
</pre>
<source lang='javascript'>
{
"isCompany": true,
"billingAddress":
{
"organizationName": "Reseller Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code",
"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>
'''Answer''':
<pre>
HTTP/1.1 201 Created
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/resellers/4000001
</pre>
<source lang='javascript'>
{
"id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
}
</source>
==== Reseller retrieval (GET) ====
===== Reseller collection retrieval (GET) example =====
To retrieve existing resellers, the client needs to send a HTTP <code>GET</code> request on the reseller's collection resource URI <code>https://api.example.com/v1/resellers</code>.
The service responds with a HTTP status code 200 (OK) on success and returns the various resellers.
'''Request''':
<pre>
GET /v1/resellers/ HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
</pre>
'''Answer''':
<pre>
HTTP/1.1 200 OK
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
</pre>
<source lang='javascript'>
[
{
"id": 4000000,
"location": "https://api.example.com/v1/resellers/4000000",
"isCompany": true,
"descriptiveName": "stepping stone GmbH"
},
{
"id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
"isCompany": true,
"descriptiveName": "Company Name or Givenname Surname"
}
]
</source>
===== Reseller element retrieval (GET) example =====
To retrieve an existing reseller and fetch the informations 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 informations.
'''Request''':
<pre>
GET /v1/resellers/4000001 HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
</pre>
'''Answer''':
<pre>
HTTP/1.1 200 OK
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
</pre>
<source lang='javascript'>
{
"id": 4000001,
"isCompany": true,
"billingAddress":
{
"organizationName": "Reseller Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code",
"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/"
}
"shippingAddresses":
[
TBD,
]
}
</source>
==== Reseller update (PUT) ====
To updates an existing reseller, the client needs to send a HTTP <code>PUT</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.
The <code>PUT</code> method requires one to sent the complete record, thus the work-flow is normally as follows:
# A [[#Reseller_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
# Send a <code>PUT</code> request with all the reseller data
'''Request''':
<pre>
PUT /v1/resellers/4000001 HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
Content-Type: application/json
</pre>
<source lang='javascript'>
{
"id": 4000001,
"isCompany": true,
"billingAddress":
{
"organizationName": "Reseller Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "Postal Code",
"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/"
}
"shippingAddresses":
[
TBD,
]
}
</source>
'''Answer''':
<pre>
HTTP/1.1 200 OK
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
</pre>
<source lang='javascript'>
</source>
==== 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.
'''Request''':
<pre>
PATCH /v1/resellers/4000001 HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
Content-Type: application/json
</pre>
<source lang='javascript'>
{
"billingAddress":
{
"postalAddress": "New Street Number",
"preferredLanguage": "de-CH"
}
}
</source>
'''Answer''':
<pre>
HTTP/1.1 200 OK
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
</pre>
<source lang='javascript'>
</source>
==== 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.
'''Request''':
<pre>
DELETE /v1/resellers/4000001 HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
</pre>
<source lang='javascript'>
</source>
'''Answer''':
<pre>
HTTP/1.1 200 OK
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
</pre>
<source lang='javascript'>
</source>
[[Category:REST API]]