FederationPersonStatesREST Resource

REST API for reading a person's status/verification fields ("Personenstatus" and "Weitere Informationen") within a federation's context. INTERNAL-scope only (SPE-17349): every method calls FederationPersonStatesREST first, independent of RestAccessFilter's path-pattern classification, so an internal-only guard is never accidentally skipped.

GET /2014/federations/{fedNickname}/personStates

Searches the status fields of every person in a federation, with optional filters and paging.

Notes required for the public contract (Enunciate documentation):

  • maxResults limits the number of persons, not status fields. A response with maxResults=1000 can contain up to 13000 field entries.
  • set=false means the field is not set, or has never been edited -- both are treated as the same thing.
  • For section=ADDITIONAL_INFORMATION entries, the confirmationDateTime time-of-day and remark are always empty by design; LSB_CERTIFICATE has no date at all. There, null means "not supported", not "empty".
  • Multiple statusField values are AND-combined: a matching person satisfies set (and, if given, the confirmation-date range) for every listed key.
  • confirmedFrom/confirmedTo filter on the confirmation date, not on any modification date.
  • The PERSON_STATUS area is only populated when the federation has it enabled (personStatusEnabled).

Request Parameters
name type description constraints multivalued
fedNickname path the nickname of the federation   no
activeAt query the point in time role/licence validity is evaluated at, as a local date-time without a time-zone offset (yyyy-MM-ddTHH:mm:ss); default "now"   no
confirmedFrom query start of the confirmation-date range filter, as a local date-time without a time-zone offset (yyyy-MM-ddTHH:mm:ss)   no
confirmedTo query end of the confirmation-date range filter, as a local date-time without a time-zone offset (yyyy-MM-ddTHH:mm:ss)   no
federationRole query filter: person holds this federation role   no
firstResult query index of the first person for paging; default 0 int no
firstname query filter: person's first name (prefix match)   no
includeLowerRegions query whether region's sub-regions are included; default true boolean no
includeUnset query whether fields with set=false are included per person; default true boolean no
lastname query filter: person's last name (prefix match)   no
licence query filter: person holds this licence (or one requiring it)   no
maxResults query maximum number of persons; default 100, capped at 1000 int no
personId query filter: a specific person int no
region query filter: person's region   no
set query whether the listed statusField keys must be set or unset boolean no
statusField query zero or more status field keys to filter on; AND-combined   yes
Response Body
media type data type description
application/json PersonStatusFieldsListDTO (JSON) the paged list of persons with their status fields
application/xml personStatusFieldsList (XML)

Example

Request
GET /2014/federations/{fedNickname}/personStates
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "firstResult" : 12345,
  "availableResults" : 12345,
  "maxResults" : 12345,
  "person" : [ {
    "personStatusEnabled" : true,
    "personStatusField" : [ {
      "name" : "...",
      "section" : "ADDITIONAL_INFORMATION",
      "remark" : "...",
      "set" : true,
      "confirmationDateTime" : "...",
      "key" : "PREVENTION_SEXUALISED_VIOLENCE"
    }, {
      "name" : "...",
      "section" : "ADDITIONAL_INFORMATION",
      "remark" : "...",
      "set" : true,
      "confirmationDateTime" : "...",
      "key" : "CERTIFICATE_TRAINER_EXEMPTION"
    } ],
    "firstname" : "...",
    "personUri" : "...",
    "lastname" : "...",
    "personId" : 12345,
    "internalId" : "...",
    "fedNickname" : "..."
  }, {
    "personStatusEnabled" : true,
    "personStatusField" : [ {
      "name" : "...",
      "section" : "ADDITIONAL_INFORMATION",
      "remark" : "...",
      "set" : true,
      "confirmationDateTime" : "...",
      "key" : "CODE_OF_HONOR"
    }, {
      "name" : "...",
      "section" : "PERSON_STATUS",
      "remark" : "...",
      "set" : true,
      "confirmationDateTime" : "...",
      "key" : "CERTIFICATE_SELF_RELIANCE"
    } ],
    "firstname" : "...",
    "personUri" : "...",
    "lastname" : "...",
    "personId" : 12345,
    "internalId" : "...",
    "fedNickname" : "..."
  } ]
}

GET /2014/federations/{fedNickname}/personStates/{internalId}

Gets the status fields for one person.

Request Parameters
name type description default constraints
fedNickname path the nickname of the federation the person is looked up in; required. Without a federation context, the "Weitere Informationen" area, its feature gates, and the configurable "Ehrenkodex" label are undefined.    
internalId path the person's internalID (consistent with the sibling /address and /federationRoles resources, which both resolve via TOPerson.fetchForInternalID)    
includeUnset query whether fields with set=false are included. set=false covers both "field not set" and "field never edited" -- these are treated as equivalent. Default true. true boolean
Response Body
media type data type description
application/json PersonStatusFieldsDTO (JSON) the person's status fields
application/xml personStatusFields (XML)

Example

Request
GET /2014/federations/{fedNickname}/personStates/{internalId}
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "personStatusField" : [ {
    "name" : "...",
    "section" : "ADDITIONAL_INFORMATION",
    "remark" : "...",
    "set" : true,
    "confirmationDateTime" : "...",
    "key" : "CODE_OF_HONOR"
  }, {
    "name" : "...",
    "section" : "ADDITIONAL_INFORMATION",
    "remark" : "...",
    "set" : true,
    "confirmationDateTime" : "...",
    "key" : "CERTIFICATE_SELF_RELIANCE"
  } ],
  "personStatusEnabled" : true,
  "firstname" : "...",
  "lastname" : "...",
  "personId" : 12345,
  "internalId" : "...",
  "fedNickname" : "...",
  "personUri" : "..."
}