Difference between revisions of "stoney core: Resellers Resource - REST API"

From stoney cloud
Jump to: navigation, search
[unchecked revision][unchecked revision]
(→‎Reseller collection etrieval request message)
(→‎Reseller creation request message body)
Line 51: Line 51:
 
! Mandatory
 
! Mandatory
 
! Description
 
! Description
−
! Allowed content
+
! Valid content
 +
! PREG
 
! Default value
 
! Default value
 
! Example
 
! Example
Line 61: Line 62:
 
|<code>true</code> if the reseller represents a company, <code>false</code> if it's an individual person.
 
|<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>
 
|<code>true</code> or <code>false</code>
 +
|
 
|
 
|
 
|<pre>isCompany: true</pre>
 
|<pre>isCompany: true</pre>
Line 69: Line 71:
 
|yes
 
|yes
 
|An object holding the billing address informations for the given reseller. Refere to the [[#billingAddress_object|billingAddress object table]] for more informations.
 
|An object holding the billing address informations for the given reseller. Refere to the [[#billingAddress_object|billingAddress object table]] for more informations.
 +
|
 
|
 
|
 
|
 
|
Line 99: Line 102:
 
!Mandatory
 
!Mandatory
 
!Description
 
!Description
−
!Allowed content
+
!Valid content
 +
![http://www.pcre.org/ PCRE]
 
!Default value
 
!Default value
 
!Example
 
!Example
Line 108: Line 112:
 
|no
 
|no
 
|The name of the organization.
 
|The name of the organization.
 +
|
 
|@TODO: Add regex
 
|@TODO: Add regex
 
|
 
|
Line 118: Line 123:
 
|The gender of the address holder
 
|The gender of the address holder
 
|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.
 
|Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral.
 +
|
 
|
 
|
 
|<pre>"gender": "f"</pre>
 
|<pre>"gender": "f"</pre>
Line 126: Line 132:
 
|yes
 
|yes
 
|The given name (first name or forename) of the address holder.
 
|The given name (first name or forename) of the address holder.
 +
|
 
|@TODO: Add regex
 
|@TODO: Add regex
 
|
 
|
Line 135: Line 142:
 
|yes
 
|yes
 
|The surname (last name or family name) of the address holder.
 
|The surname (last name or family name) of the address holder.
 +
|
 
|@TODO: Add regex
 
|@TODO: Add regex
 
|
 
|
Line 143: Line 151:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 152: Line 161:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 161: Line 171:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 170: Line 181:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 179: Line 191:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 188: Line 201:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 197: Line 211:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 206: Line 221:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex
Line 215: Line 231:
 
|string
 
|string
 
|yes
 
|yes
 +
|
 
|
 
|
 
|@TODO: Add regex
 
|@TODO: Add regex

Revision as of 13:05, 27 December 2013

Overview

The resellers resource represents the bla, bla, bla...

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 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

Reseller Object
Parameter name Data type Mandatory Description Valid content PREG 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/"
}
billingAddress Object
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

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

Reseller Creation Response Object
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)

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 informations.

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: application/json
Request body <Empty> 




Reseller element retrieval (GET)


To retrieve an existing reseller and fetch the informations 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 informations.



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: application/json






 Request body

 <Empty>

 




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:



    

  1.  A GET request on the Reseller element URI will be made to fetch the whole document.

    2. 

  2.  Update the fields which content has changed

    3. 

  3.  Send a PUT request with all the reseller data

    4. 



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 deletion (DELETE)


To delete an existing reseller, the client needs to send a HTTP DELETE 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.



Links




								

				Retrieved from "http://wiki.stoney-cloud.org/mediawiki/index.php?title=stoney_core:_Resellers_Resource_-_REST_API&oldid=2466"