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

Overview

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

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

People resource methods

Person creation (POST)

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

Person creation request message

HTTP request part

Content

Example

Request lines

POST <Request-URI> HTTP 1.1
HOST: <Host>

POST /v1/people/ 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

{ ... }

Person creation request message body

Person Object
Parameter name	Data type	Mandatory	Description	Valid content	PCRE	Default value	Example
`gender`	string	yes	The gender of the address holder	Either `f` for female, `m` for male or `n` for neutral.			"gender": "f"
`title`	string	no	The title of a person.	UTF-8 {64}	@TODO add regex		"title": "CEO"
`isActive`	boolean	no	Is the entry active	`true` or `false`		`true`	"isActive": true
`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"
`preferredLanguage`	string	yes	Language tag	[ISO 639-1 Code]-[ISO 3166-1-alpha-2 code]			"preferredLanguage": "de-CH"
`password`	string	yes	Password	min 8 chars, max 255 chars			"password": "dontstealme!"
`mail`	string	yes	Email address		@TODO: Add regex		"mail": "user@example.com"
`telephoneNumber`	string	yes	Telephone number	Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line)			"telephoneNumber": "+41 11 222 33 44"
`mobileTelephoneNumber`	string	yes	Mobile telephone	Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line).			"mobileTelephoneNumber": "+41 11 222 33 44"
`timeZoneOffset`	string	yes	Time zone as an offset from UTC.	Offset from UTC in the form `UTC±[hh]:[mm]`			"timeZoneOffset": "UTC+01:00"
`belongsToCustomerId`	integer	yes	the customer UID the person belongs to		@TODO add regex		"belongsToCustomerId": 4000002
`employeeOfId`	array	no	The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers	one ore more UID as integer			"employeeOfId": [ 4000002, 4001003, 4002004 ]
`externalId`	integer	no	The ID of a reference in an external database.	Min 0, max 1e+32			"externalId": 987654321

Person 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/people/5000001

Response body

JSON object

{ ... }

Person creation response message body

Person Creation Response Object
Parameter name	Data type	Mandatory	Description	Valid content	PCRE	Example
`id`	integer	yes	The identification number of the newly created person resource.		@TODO add regex	"id": 5000001
`location`	string	yes	The location URI of the newly created person resource, corresponds with the HTTP location header.	@TODO add link to URI RFC		"location": "https://api.example.com/v1/people/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": { /* ... */ }

People retrieval (GET)

People collection retrieval (GET)

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

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

Search (fulltext)

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

People collection retrieval request message

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

People 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/people?page=1&per_page=30>; rel="first",
  <https://api.example.com/v1/people?page=2&per_page=30>; rel="prev",
  <https://api.example.com/v1/people?page=4&per_page=30>; rel="next",
  <https://api.example.com/v1/people?page=10&per_page=30>; rel="last"
X-Total-Count: 295

Response body

JSON object

{ ... }

People collection retrieval response message body

Parameter name

Data type

Mandatory

Description

Valid content

PCRE

Default value

Example

array

no

An array with one or more person collection objects

[
  {
    "id": 5000000,
    "location": "https://api.example.com/v1/people/5000000",
    "title": "CEO",
    "isActive": true,
    "givenName": "Name",
    "surname", "Surname",
    "mail", "user@example.com",
    "preferredLanguage": "de-CH",
    "belongsToResellerId": 4000000,
    "belongsToCustomerId": 4000001,
    "employeeOfId": [
      4000002,
      4001003,
      4002004
    ]
  },
  {
    /* ... */
  }
]

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

Person Collection Array Element Object
Parameter name	Data type	Mandatory	Description	Valid content	PCRE	Default value	Example
`id`	integer	yes	The identification number of the person.		@TODO add regex		"id": 5000000
`location`	string	yes	The location URI of the person resource.	@TODO add link to URI RFC			"location": "https://api.example.com/v1/people/5000000"
`isActive`	boolean	yes		`true` or `false`		`true`	"isActive": true
`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"
`mail`	string	yes	Email address		@TODO: Add regex		"mail": "user@example.com"
`preferredLanguage`	string	yes	Language tag	[ISO 639-1 Code]-[ISO 3166-1-alpha-2 code]			"preferredLanguage": "de-CH"
`belongsToResellerId`	integer	yes	The reseller's identification number the person belongs to.		@TODO add regex		"belongsToResellerId": 4000000
`belongsToCustomerId`	integer	yes	The customer's identification number the person belongs to		@TODO add regex		"belongsToCustomerId": 4000002
`employeeOfId`	array	no	The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers	one ore more UID as integer			"employeeOfId": [ 4000002, 4001003, 4002004 ]

Person element retrieval (GET)

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

Person element retrieval request message

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

Person 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/people/5000001

Response body

JSON object

{ ... }

Person element retrieval response message body

Person Element Retrieval Response Object
Parameter name	Data type	Mandatory	Description	Valid content	PCRE	Default value	Example
`id`	integer	yes	The identification number of the person.		@TODO add regex		"id": 5000001
`gender`	string	yes	The gender of the address holder	Either `f` for female, `m` for male or `n` for neutral.			"gender": "f"
`title`	string	no	The title of a person.	UTF-8 {64}	@TODO add regex		"title": "CEO"
`isActive`	boolean	yes		`true` or `false`		`true`	"isActive": true
`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"
`preferredLanguage`	string	yes	Language tag	[ISO 639-1 Code]-[ISO 3166-1-alpha-2 code]			"preferredLanguage": "de-CH"
`mail`	string	yes	Email address		@TODO: Add regex		"mail": "user@example.com"
`telephoneNumber`	string	yes	Telephone number	Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line)			"telephoneNumber": "+41 11 222 33 44"
`mobileTelephoneNumber`	string	yes	Mobile telephone	Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line).			"mobileTelephoneNumber": "+41 11 222 33 44"
`timeZoneOffset`	string	yes	Time zone as an offset from UTC.	Offset from UTC in the form `UTC±[hh]:[mm]`			"timeZoneOffset": "UTC+01:00"
`belongsToResellerId`	integer	yes	The reseller's identification number the person belongs to.		@TODO add regex		"belongsToResellerId": 4000000
`resellers`	string	yes	The reseller's location URI the person belongs to.	A valid reseller's location element URI	@TODO add link to URI RFC		"resellers": "https://api.example.com/v1/resellers/4000000"
`belongsToCustomerId`	integer	yes	The customer's UID the person belongs to		@TODO add regex		"belongsToCustomerId": 4000002
`customers`	string	yes	The customer's location URI the person belongs to.	A valid customer's location element URI	@TODO add link to URI RFC		"customers": "https://api.example.com/v1/customers/4000002"
`employeeOfId`	array	no	The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers	one ore more UID as integer			"employeeOfId": [ 4000002, 4001003, 4002004 ]
`externalId`	integer	no	The ID of a reference in an external database.	Min 0, max 1e+32			"externalId": 987654321
`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": { /* ... */ }

Person update (PUT)

To updates an existing person, the client needs to send a HTTP PUT request on the person's element resource URI (such as, https://api.example.com/v1/people/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:

A GET request on the Person element URI will be made to fetch the whole document.
Update the fields which content has changed
Send a PUT request with all the person data

Person update request message

HTTP request part

Content

Example

Request lines

PUT <Request-URI> HTTP 1.1
HOST: <Host>

PUT /v1/people/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

{ ... }

Person update request message body

See Person object.

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

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

Person partly update (PATCH)

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

Person partly update request message

HTTP request part

Content

Example

Request lines

PATCH <Request-URI> HTTP 1.1
HOST: <Host>

PATCH /v1/people/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

{ ... }

Person partly update request message body

The JSON message body consists out of one or more fields from the Person object.

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

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

Person deletion (DELETE)

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

Person deletion request message

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

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

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

People search

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

Links

stoney core: REST API

stoney core: People Resource - REST API

Contents

Overview

People resource methods

Person creation (POST)

Person creation request message

Person creation request message body

Person creation response message

Person creation response message body

People retrieval (GET)

People collection retrieval (GET)

Sort

Search (fulltext)

Search (with filter)

People collection retrieval request message

People collection retrieval response message

People collection retrieval response message body

Person element retrieval (GET)

Person element retrieval request message

Person element retrieval response message

Person element retrieval response message body

Person update (PUT)

Person update request message

Person update request message body

Person update response message

Person update response message body

Person partly update (PATCH)

Person partly update request message

Person partly update request message body

Person partly update response message

Person partly update response message body

Person deletion (DELETE)

Person deletion request message

Person deletion response message

Person deletion response message body

People search

Links

Navigation menu

Search