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 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>
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
|
|
|
|
isActive
|
boolean
|
yes
|
|
true or false
|
|
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, but can also be the name of a brand.
|
|
|
|
"resellerName": "Super-duper Hosting"
|
billingAddress
|
object
|
yes
|
An object holding the billing address informations for the given reseller. Refer 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/"
}
|
shippingAddress
|
object
|
no
|
An object holding the shipping address informations for the given reseller. Refer to the shippingAddress object table for more informations.
|
|
|
|
"shippingAddress":
{
"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.
|
|
|
|
givenName
|
string
|
yes
|
The given name (first name or forename) of the address holder.
|
|
@TODO: Add regex
|
|
|
surname
|
string
|
yes
|
The surname (last name or family name) of the address holder.
|
|
@TODO: Add regex
|
|
|
postalAddress
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
countryCode
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
postalCode
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
localityName
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
preferredLanguage
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
mail
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
telephoneNumber
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
mobileTelephoneNumber
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
"mobileTelephoneNumber": ""
|
websiteURL
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
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.
|
|
|
|
givenName
|
string
|
yes
|
The given name (first name or forename) of the address holder.
|
|
@TODO: Add regex
|
|
|
surname
|
string
|
yes
|
The surname (last name or family name) of the address holder.
|
|
@TODO: Add regex
|
|
|
postalAddress
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
countryCode
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
postalCode
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
localityName
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
preferredLanguage
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
mail
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
telephoneNumber
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
mobileTelephoneNumber
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
"mobileTelephoneNumber": ""
|
websiteURL
|
string
|
yes
|
|
|
@TODO: Add regex
|
|
|
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: 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
|
|
|
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.
|
|
|
|
|
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-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 201 Created
|
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"
},
{
/* ... */
}
]
|
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.
|
|
|
|
|
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
|
|
|
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
|
|
|
|
isActive
|
boolean
|
yes
|
|
true or false
|
|
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, but can also be the name of a brand.
|
|
|
|
"resellerName": "Super-duper Hosting"
|
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-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 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 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
|
|
|
isCompany
|
boolean
|
yes
|
true if the reseller represents a company, false if it's an individual person.
|
true or false
|
|
|
|
isActive
|
boolean
|
yes
|
|
true or false
|
|
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, but can also be the name of a brand.
|
|
|
|
"resellerName": "Super-duper Hosting"
|
billingAddress
|
object
|
yes
|
An object holding the billing address informations for the given reseller. Refer 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/"
}
|
shippingAddress
|
object
|
no
|
An object holding the shipping address informations for the given reseller. Refer to the shippingAddress object table for more informations.
|
|
|
|
"shippingAddress":
{
"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/"
}
|
customers
|
string
|
yes
|
The location URI of the customers belonging to this reseller resource.
|
@TODO add link to URI RFC
|
|
|
"location": "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
|
|
|
"location": "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
|
|
|
"location": "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 informations.
|
|
|
|
|
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>
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 update response message body
Reseller Update Response Object
Parameter name
|
Data type
|
Mandatory
|
Description
|
Valid content
|
PCRE
|
Default value
|
Example
|
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.
|
|
|
|
|
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
One or more of the fields from the 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>
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 partly update response message body
On success (200
an empty response message body will be returned, otherwise an error object will provide further informations about the failure.
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