Difference between revisions of "stoney core: Resellers Resource - REST API"
[unchecked revision] | [unchecked revision] |
(→Reseller retrieval (GET)) |
(→Reseller update (PUT)) |
||
Line 298: | Line 298: | ||
== Reseller update (PUT) == | == 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 | ||
+ | |||
== Reseller partly update (PATCH) == | == Reseller partly update (PATCH) == | ||
== Reseller deletion (DELETE) == | == Reseller deletion (DELETE) == |
Revision as of 17:29, 12 December 2013
Contents
Overview
The resellers resource represents the bla, bla, bla...
Reseller 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 informations.
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 informations 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> Content-Type: <Type>/<Subtype> |
Accept: application/json Content-Type: application/json |
Request body | JSON object | { ... } |
Reseller creation request message body
Parameter name | Data type | Mandatory | Description | Allowed content | 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 | |
billingAddress
|
object | yes | An object holding the billing address informations for the given reseller. Refere to the billingAddress object table for more informations. | "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/" } |
Parameter name | Data type | Mandatory | Description | Allowed content | 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
Status Line | Content | Example |
---|---|---|
Request lines | 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: 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 | Allowed content | 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 informations. | error { ... } |
Reseller 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.
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