stoney core: Resellers Resource - REST API

From stoney cloud
Jump to: navigation, search

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

Reseller Object
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/"
}
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. 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": ""
shippingAddress 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

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

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




Reseller Collection Retrieval Response Object



 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 { /* ... */  }











Reseller Collection Array Element Object



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




Reseller Element Retrieval Response Object



 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:



    

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



Links







								

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