Period

A Period is the validity interval of a record: the dates between which the record is considered current. It is the mechanism behind historicization — when a record is historicized its period is closed, so the record disappears from normal queries while remaining readable in history.

start_date defaults to 1970-01-01 (open on the left) and end_date to 9999-12-31 (open on the right), so a record left with the default values is valid at any date.

Use this API to:

• Read the validity interval of a record (filter by entity_id)
• Correct the dates of a period, for example to reopen a record closed by mistake

Version

1.0.0

OpenAPI version

3.0.0

Operations

view

GET

/period/view/{id}

Retrieve the periods of the entity identified by the given ID.

Authorizations

• Oauth2
• AccessToken

Path Parameters

id

required

string

The ID of the entity

Responses

200

The periods for the entity

Current entity periods response

object

entity_type

Current entity type

string

ACTION

entity_name

Current entity label

string

Base safety (4 hours)

owned

Owned entity periods

Array<object>

object

period_id

Unique identifier for the period

string

example-period-id

data

Additional data, unused

object

start_date

Start period date (default -infinitive)

string

default: 1970-01-01 00:00:00

2017-01-01 00:00:00

end_date

End period date (default +infinitive)

string

default: 9999-12-31 23:59:59

2019-09-26 00:00:00

entity_id

Unique identifier for entity

string

example-action-id

entity_name

Entity label

string

Base safety (4 hours)

entity_type

Entity type

string

ACTION

child

The list of all child (direct and not-direct) periods indexed by child entity_id

object

example-action-subscription-id

Child entity_id

Array<object>

object

dep_id

Parent entity_id

string

example-action-id

dep_type

Parent entity_type

string

ACTION

start_date

Start period date (default -infinitive)

string

default: 1970-01-01 00:00:00

2017-01-01 00:00:00

end_date

End period date (default +infinitive)

string

default: 9999-12-31 23:59:59

2019-09-26 00:00:00

entity_id

Unique identifier for entity

string

example-action-subscription-id

entity_name

Entity label

string

Jon Snow on Base safety (4 hours)

entity_type

Entity type

string

ACTION_SUBSCRIPTION

level

Nesting level

string

0

parent

The list of all parent (direct and not-direct) periods indexed by parent entity_id

object

example-office-id

Parent entity_id

Array<object>

object

dep_id

Unique identifier for parent entity

string

example-office-id

dep_type

Parent entity_type

string

OFFICE

dep_name

Parent entity label

string

San Jose central office

start_date

Start period date (default -infinitive)

string

default: 1970-01-01 00:00:00

2017-01-01 00:00:00

end_date

End period date (default +infinitive)

string

default: 9999-12-31 23:59:59

2019-09-26 00:00:00

entity_id

Unique identifier for current entity

string

example-action-id

entity_type

Current entity type

string

ACTION

level

Nesting level

string

0

Example

{
  "entity_type": "ACTION",
  "entity_name": "Base safety (4 hours)",
  "owned": [
    {
      "period_id": "example-period-id",
      "data": null,
      "start_date": "2017-01-01 00:00:00",
      "end_date": "2019-09-26 00:00:00",
      "entity_id": "example-action-id",
      "entity_name": "Base safety (4 hours)",
      "entity_type": "ACTION"
    }
  ],
  "child": {
    "example-action-subscription-id": [
      {
        "dep_id": "example-action-id",
        "dep_type": "ACTION",
        "start_date": "2017-01-01 00:00:00",
        "end_date": "2019-09-26 00:00:00",
        "entity_id": "example-action-subscription-id",
        "entity_name": "Jon Snow on Base safety (4 hours)",
        "entity_type": "ACTION_SUBSCRIPTION",
        "level": "0"
      }
    ]
  },
  "parent": {
    "example-office-id": [
      {
        "dep_id": "example-office-id",
        "dep_type": "OFFICE",
        "dep_name": "San Jose central office",
        "start_date": "2017-01-01 00:00:00",
        "end_date": "2019-09-26 00:00:00",
        "entity_id": "example-action-id",
        "entity_type": "ACTION",
        "level": "0"
      }
    ]
  }
}

update

PUT

/period/update/{id}

Update the periods of the entity identified by the given ID.

Authorizations

• Oauth2
• AccessToken

Path Parameters

id

required

string

The ID of the entity

Request Body

The periods to update

Update entity periods request body

object

periods

Array<object>

A period to write

object

period_id

Unique identifier for the period

string

example-period-id

start_date

Start period date (default -infinitive)

string

default: 1970-01-01 00:00:00

2017-01-01 00:00:00

end_date

End period date (default +infinitive)

string

default: 9999-12-31 23:59:59

2019-09-26 00:00:00

Example

{
  "periods": [
    {
      "period_id": "example-period-id",
      "start_date": "2017-01-01 00:00:00",
      "end_date": "2019-09-26 00:00:00"
    }
  ]
}

Update entity periods request body

object

periods

Array<object>

A period to write

object

period_id

Unique identifier for the period

string

example-period-id

start_date

Start period date (default -infinitive)

string

default: 1970-01-01 00:00:00

2017-01-01 00:00:00

end_date

End period date (default +infinitive)

string

default: 9999-12-31 23:59:59

2019-09-26 00:00:00

Responses

200

The updated action

Update entity periods response body

object

Example

{
  "done": "true"
}

Update entity periods response body

object

Example

{
  "done": "true"
}