stoney core: Resellers Resource Mapping (REST - LDAP)

From stoney cloud
Jump to: navigation, search

Also visit stoney core: Resellers Resource - REST API.

Overview

The resellers resource mapping describes the business logic behind the LDAP to JSON transformation and visa versa for the request and response objects. The actual resellers resource REST API is located in the REST API category and is named stoney core: Resellers Resource - REST API.

Principles:

  • For the resource objects there is most of the time a one-to-one mapping between LDAP attributes and JSON object.
  • For collections only a subset of the resource object attributes will be returned which may be also be merged or otherwise mangled.

This specification puts together the Reseller frontend API (stoney core: Resellers Resource - REST API) and the LDAP Data Backend (stoney core: OpenLDAP directory data organisation).

If nothing else is defined, address related information is always taken out of the billing address (ou=address,uid=<UID>,ou=resellers,dn=stoney-cloud,dc=org).

Resellers Resource Mapping

If not specified otherwise, the following rules apply:

  • an attribut which exists in the LDAP object but has no corresponding entry in the API will never be exported
  • the mapping has always to be explicit for the API attributes: it is always considered an error if the client provides an attribute which is not listed below (aka no hidden attributes)
  • whether an attribute is mandatory or not is specified by the corresponding LDAP object and/or REST API specification
  • the attribute in bold letters is the REST API ressource identifier and can as such never be specified in a POST request but will always be generated on the server side
  • specifying a read-only attribut in a PUT or PATCH request is allowed as long as the value is the same as currently set
  • the mapping applies to create (POST), read (GET) and update (PATCH or PUT). For delete (DELETE) the REST principles apply
  • strings are encoded and stored in in UTF-8
    • if an attribute in the backend does not support UTF-8 strings (attributes which permit ASCII/7-bit character encoding only), the attribute should not be exported via the API must generated from other fields and the internal transliteration should be done via POSIX iconv

Base DN: dc=stoney-cloud,dc=org

API Attribute LDAP Object DN LDAP Attribute Details
Reseller uid (per Reseller)
id uid=4000000,ou=reseller uid Always read-only.
isCompany uid=4000000,ou=reseller sstIsCompany
isActive uid=4000000,ou=reseller sstIsActive
resellerName uid=4000000,ou=reseller organizationName
(none) uid=4000000,ou=reseller sstExternalID
(none) uid=4000000,ou=reseller sstBelongsToResellerUID Internally set to the same value as uid
organizationName ou=address,uid=4000000,ou=reseller organizationName
Reseller Billing Address
address.gender ou=address,uid=4000000,ou=reseller sstGender
address.givenName ou=address,uid=4000000,ou=reseller givenName
address.surname ou=address,uid=4000000,ou=reseller surname
address.postalAddress ou=address,uid=4000000,ou=reseller postalAddress
address.postOfficeBox ou=address,uid=4000000,ou=reseller postOfficeBox
address.stateOrProvinceName ou=address,uid=4000000,ou=reseller stateOrProvinceName
address.countryName ou=address,uid=4000000,ou=reseller countryName
address.postalCode ou=address,uid=4000000,ou=reseller postalCode
address.localityName ou=address,uid=4000000,ou=reseller localityName
address.preferredLanguage ou=address,uid=4000000,ou=reseller preferredLanguage
address.mail ou=address,uid=4000000,ou=reseller mail
address.telephoneNumber ou=address,uid=4000000,ou=reseller telephoneNumber
address.mobileTelephoneNumber ou=address,uid=4000000,ou=reseller mobileTelephoneNumber
address.websiteURL ou=address,uid=4000000,ou=reseller sstWebsiteURL

Resellers Collection Mapping

If not specified otherwise, the following rules apply:

  • the table below lists one entry in the collection/array/list to be returned
  • additional attributes like pagination-headers, location attribute, etc. are not part of this spec but must be part of the final object, as per stoney core: Resellers Resource - REST API
  • the attributes listed below are either needed for displaying the list of resellers or for displaying a reseller in the global full-text search results

Base DN: dc=stoney-cloud,dc=org

API Attribute LDAP Object DN LDAP Attribute Details
id uid=4000000,ou=reseller uid
resellerName uid=4000000,ou=reseller organizationName
contactGivenName ou=address,uid=4000000,ou=reseller givenName
contactSurname ou=address,uid=4000000,ou=reseller surname
contactMail ou=address,uid=4000000,ou=reseller mail
contactPhone ou=address,uid=4000000,ou=reseller telephoneNumber or mobileTelephoneNumber or (none) both attributes are optional, therefore this attribute may not be available
contactCountryCode ou=address,uid=4000000,ou=reseller countryCode
contactPostalCode ou=address,uid=4000000,ou=reseller postalCode
contactLocalityName ou=address,uid=4000000,ou=reseller localityName

Reseller retrieval (GET)

Reseller collection retrieval (GET)

Reseller collection retrieval (GET) Mapping

Reseller element retrieval (GET)

The following sequence describes the reseller element retrieval:

  1. Look-up the reseller in the OpenLDAP directory in the ou=reseller,dc=stoney-cloud,dc=org sub tree (with a configurable LDAP service user): ...
  2. Billing address ou=address,uid=<UID>,ou=reseller,dc=stoney-cloud,dc=org (mandatory)
  3. Shipping ou=shipping,uid=4000000,ou=reseller,dc=stoney-cloud,dc=org contains the shipping address and is optional (it is only needed, if the shipping address differs from the billing Address).

Reseller element retrieval (GET) Mapping

Reseller deletion (DELETE)

TBD: Describe, what to check before a reseller can be deleted (no customers, no people and later no services).

Probably: sstBelongsToResellerUID

API Attribute LDAP Attribute
id uid

Links