stoney core: Customers Resource - REST API

From stoney cloud
Jump to: navigation, search

Also visit stoney core: Customers Resource Mapping (REST - LDAP).

Overview

The REST API describes the (Representational State Transfer Application Programming Interface) of the customers 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 customer (POST).
  • Retrieve multiple customers in the form of a list (GET).
  • Retrieve a single customer (GET).
  • Update an existing customer (PUT).
  • Update one or more values of an existing customer (PATCH).
  • Delete a single customer (DELETE).

To get an idea what happens behind the screens, have a look at the stoney core: Customers Resource Mapping (REST - LDAP) documentation located in the Mapping (REST - LDAP) category.

Customers resource methods

Customer creation (POST)

To create a new customer the client needs to send a HTTP POST request on the customer collection resource URI https://api.example.com/v1/customers (also see Base URI), including the associated customer information. The service will generate a new customer and responds with a HTTP status code 201 (Created) on success. The newly created customer URI is returned within the HTTP location header, which can be used by the client to gather information about the new customer.

Customer creation request message

HTTP request part Content Example
Request lines
POST <Request-URI> HTTP 1.1
HOST: <Host>
POST /v1/customers/ 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
{ ... }

Customer creation request message body

Customer Object
Parameter name Data type Mandatory Description Valid content PCRE Default value Example
isCompany boolean yes true if the customer represents a company, false if it's an individual person. true or false
"isCompany": true
isActive boolean yes true or false true
"isActive": true
customerName string yes The customer's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object. UTF-8 {64}
"customerName": "Customer Ltd."
billingAddress object yes An object holding the billing address information for the given customer. Refer to the billingAddress object table for more information.
"billingAddress":
{
  "organizationName": "Customer 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 customer. Refer to the shippingAddress object table for more information.
"shippingAddress":
{
  "organizationName": "Customer 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/"
}
externalID string no An optional external ID the customer belongs to (is used for the mapping to external databases). @TODO add regex
"externalID": 12345
belongsToResellerID integer yes The reseller identification number the customer resource must belong to. @TODO add regex
"belongsToResellerID": 4000000
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": "Customer 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": "Customer 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": ""

Customer 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/customers/5000001
Response body JSON object
{ ... }

Customer creation response message body

Customer 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 customer resource. @TODO add regex
"id": 5000001
location string yes The location URI of the newly created customer resource, corresponds with the HTTP location header. @TODO add link to URI RFC
"location": "https://api.example.com/v1/customers/5000001"
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": { /* ... */  }

Customer retrieval (GET)

Customer collection retrieval (GET)

To retrieve existing customers, the client needs to send a HTTP GET request on the customer's collection resource URI https://api.example.com/v1/customers. The service responds with a HTTP status code 200 (OK) on success and returns the various customers.

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/customers?sort=customerName,isActive. For further information on filtering, sorting and searching, visit stoney core: REST API.

Search (fulltext)

To form a fulltext search (customers only), append the url query parameter q with the desired search text: https://api.example.com/v1/customers?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 customerName) with the desired search text: https://api.example.com/v1/customers?customerName=example. You're allowed to search for all attributes that are returned in the Customer element retrieval response message body.

Customer collection retrieval request message

HTTP request part Content Example
Request lines
GET <Request-URI> HTTP 1.1
HOST: <Host>
GET /v1/customers/ 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>

Customer 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/customers?page=1&per_page=30>; rel="first",
  <https://api.example.com/v1/customers?page=2&per_page=30>; rel="prev",
  <https://api.example.com/v1/customers?page=4&per_page=30>; rel="next",
  <https://api.example.com/v1/customers?page=10&per_page=30>; rel="last"
X-Total-Count: 295
Response body JSON object
{ ... }
Customer collection retrieval response message body
Customer Collection Retrieval Response Object
Parameter name Data type Mandatory Description Valid content PCRE Default value Example


array no An array with one or more customer collection objects
[
  {
    "id": 5000000,
    "location": "https://api.example.com/v1/customers/5000000",
    "isCompany": true,
    "isActive": true,
    "customerName": "Customer Ltd."
    "countryCode": "CH",
    "postalCode": "3012",
    "localityName": "Bern",
    "belongsToResellerID": 4000000
  },
  {
    /* ... */
  }
]
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 { /* ... */  }


Customer Collection Array Element Object
Parameter name Data type Mandatory Description Valid content PCRE Default value Example
id integer yes The identification number of the customer. @TODO add regex
"id": 5000000
location string yes The location URI of the customer resource. @TODO add link to URI RFC
"location": "https://api.example.com/v1/customers/5000000"
isCompany boolean yes true if the customer represents a company, false if it's an individual person. true or false
"isCompany": true
isActive boolean yes true or false true
"isActive": true
customerName string yes The customer's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object.
"customerName": "Customer 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
belongsToResellerID integer yes The reseller identification number the customer resource must belong to. @TODO add regex
"belongsToResellerID": 4000000

Customer element retrieval (GET)

To retrieve an existing customer and fetch the information associated with it, the client needs to send a HTTP GET request on the customer's element resource URI (such as https://api.example.com/v1/customers/5000001. The service responds with a HTTP status code 200 (OK) on success and returns the associated customer information.

Customer element retrieval request message

HTTP request part Content Example
Request lines
GET <Request-URI> HTTP 1.1
HOST: <Host>
GET /v1/customers/5000001 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>

Customer 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/customers/5000001
Response body JSON object
{ ... }
Customer element retrieval response message body
Customer Element Retrieval Response Object
Parameter name Data type Mandatory Description Valid content PCRE Default value Example
id integer yes The identification number of the customer. @TODO add regex
"id": 5000001
isCompany boolean yes true if the customer represents a company, false if it's an individual person. true or false
"isCompany": true
isActive boolean yes true or false true
"isActive": true
customerName string yes The customer's display name. Mostly the same as the organizationName or the givenName and surname out of the billingAddress object.
"customerName": "Customer Ltd."
externalID string no An optional external ID the customer belongs to (is used for the mapping to external databases). @TODO add regex
"externalID": 12345
belongsToResellerID integer yes The reseller identification number the customer resource must belong to. @TODO add regex
"belongsToResellerID": 4000000
billingAddress object yes An object holding the billing address information for the given customer. Refer to the billingAddress object table for more information.
"billingAddress":
{
  "organizationName": "Customer 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 customer. Refer to the shippingAddress object table for more information.
"shippingAddress":
{
  "organizationName": "Customer 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/"
}
employees string yes The location URI of the employees belonging to this customer resource. @TODO add link to URI RFC
"employees": "https://api.example.com/v1/customers/5000001/employees"
users string yes The location URI of the users belonging to this customer resource. @TODO add link to URI RFC
"users": "https://api.example.com/v1/customers/5000001/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": { /* ... */  }

Customer update (PUT)

To updates an existing customer, the client needs to send a HTTP PUT request on the customer's element resource URI (such as, https://api.example.com/v1/customers/5000001). 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 Customer element URI will be made to fetch the whole document.
  2. Update the fields which content has changed
  3. Send a PUT request with all the customer data

Customer update request message

HTTP request part Content Example
Request lines
PUT <Request-URI> HTTP 1.1
HOST: <Host>
PUT /v1/customers/5000001 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
{ ... }

Customer update request message body

See Customer object.

Customer 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
{ ... }

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

Customer partly update (PATCH)

To update fields of an existing customer, the client needs to send a HTTP PATCH request on the customer's element resource URI (such as, https://api.example.com/v1/customers/5000001). 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.

Customer partly update request message

HTTP request part Content Example
Request lines
PATCH <Request-URI> HTTP 1.1
HOST: <Host>
PATCH /v1/customers/5000001 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
{ ... }

Customer partly update request message body

The JSON message body consists out of one or more fields from the Customer object. @TODO: Add example.

Customer 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
{ ... }

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

Customer deletion (DELETE)

To delete an existing customer, the client needs to send a HTTP DELETE request, with an empty request body on the customer's element resource URI (such as, https://api.example.com/v1/customers/5000001). The service responds with a HTTP status code 200 (OK) on success and returns an empty body.

Customer deletion request message

HTTP request part Content Example
Request lines
DELETE <Request-URI> HTTP 1.1
HOST: <Host>
DELETE /v1/customers/5000001 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>

Customer 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
{ ... }

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

Customer search

The customer search is a sub section of the stoney core: Search Resource - REST API and is described there in more detail.

Links