1. Authentication

Authentication to Portaro uses standard OAuth2 client or authorization code flows.

2. Get token

2.1. for client (e.g. Verbis app)

POST /oauth/token HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Basic <base64encodedclientandpassword>
Host: https://demo.kpsys.cz

grant_type:client_credentials

Example cURL

curl --request POST --url http://localhost/oauth/token --header "Authorization: Basic <base64encodedclientandpassword>" --data grant_type=client_credentials

2.2. for user via client

POST /oauth/token HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Basic <base64encodedclientandpassword>
Host: https://demo.kpsys.cz

grant_type:password
username:<knihovnikovo_jmeno>
password:<knihovnikovo_heslo>

Example cURL

curl --request POST --url http://localhost/oauth/token --header "Authorization: Basic <base64encodedclientandpassword>" --data grant_type=password --data username=<knihovnikovo_jmeno> --data password=<knihovnikovo_heslo>

3. Response

3.1. Example

{
  "access_token": "<access_token>",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "EVIDED EXTERNAL_SYSTEM",
  "jti": "dd6d6306-a13e-46d6-8379-92b9096fbd13"
}

4. Subsequent authorized calls

To all requests, add header

Authorization: Bearer <access_token>

4.1. Example cURL

curl --request GET --url http://localhost/api/users/current --header "Authorization: Bearer <access_token>"

5. Search

Common entrypoint for all search is /search. Main parameter for specifying what to search is kind.

Common parameters

- pageSize - page size used for pagination
- pageNumber - page number in pagination
- kind - what to search, values can be 'document', 'authority', 'exemplar', 'user'
- q - generic query parameter, used as global or 'whatewer'
- name - item name (document field 245, authority field 100, use person name, etc.)

5.1. Document search

When search for documents, specify kind=document parameter.

Specific parameters

Example 200

GET /api/search?kind=document&fond=1&name=babicka HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz
Content-Length: 0
{
    "title": "babicka",
    "subtitle": null,
    "type": "",
    "id": "LqvxiiCWQl-Je5RImqfiUw",
    "result": {
        "totalElements": 3,
        "duration": 281,
        "content": [
            {
                "fond": {
                    "id": 1,
                    "name": "Monografie",
                    "text": "Monografie"
                },
                "status": {
                    "id": 4,
                    "text": "Ukončená katalogizace"
                },
                "author": "aaaa bbbb",
                "isbn": null,
                "subTitle": "",
                "name": "Babička",
                "type": "document",
                "id": "63a6c870-cbdf-43cb-ad7b-12bd4af083b0",
                "kindedId": 97169,
                "text": "Babička",
                "exemplarable": true,
                "withForeignOccurrences": false,
                "publicationYear": 0,
                "publisher": null,
                "lastUpdateDate": "2020-11-04T14:51:42+01:00",
                "cover": null,
                "directoryId": 282019,
                "volumeable": false,
                "periodical": false
            },
            {
                "fond": {
                    "id": 1,
                    "name": "Monografie",
                    "text": "Monografie"
                },
                "status": {
                    "id": 4,
                    "text": "Ukončená katalogizace"
                },
                "author": "Němcová, Božena,",
                "isbn": null,
                "subTitle": "obrazy venkovského života",
                "name": "Babička",
                "type": "document",
                "id": "d7905d5d-0bc6-41b4-b3a8-b66c9af0a2f4",
                "kindedId": 4334,
                "text": "Babička",
                "exemplarable": true,
                "withForeignOccurrences": false,
                "publicationYear": 1961,
                "rating": null,
                "publisher": "Praha : Státní nakladatelství krásné literatury a umění, 1961",
                "lastUpdateDate": "2020-10-14T11:10:03+02:00",
                "cover": null,
                "directoryId": 19868,
                "volumeable": false,
                "periodical": false
            },
            {
                "fond": {
                    "id": 1,
                    "name": "Monografie",
                    "text": "Monografie"
                },
                "status": {
                    "id": 0,
                    "text": "Nedefinován"
                },
                "author": "Hejná, Olga,",
                "isbn": null,
                "subTitle": "",
                "name": "Tajemnica babci",
                "type": "document",
                "id": "f0e0a945-06f5-4fbb-aedb-c18bc6b0f164",
                "kindedId": 14,
                "text": "Tajemnica babci",
                "exemplarable": true,
                "withForeignOccurrences": false,
                "publicationYear": 1972,
                "rating": null,
                "publisher": "Warszawa : Nasza Księgarnia, 1972",
                "lastUpdateDate": "2020-10-19T09:25:32+02:00",
                "cover": {
                    "id": 42968,
                    "name": "obálka",
                    "text": "obálka"
                },
                "directoryId": 71034,
                "volumeable": false,
                "periodical": false
            }
        ],
        "numberOfElements": 3,
        "totalPages": 1,
        "pageNumber": 1,
        "pageSize": 10
    }
}

5.2. Authority search

When search for authorities, specify kind=authority parameter.

Specific parameters

Example 200

GET /api/search?kind=authority&fond=31&name=Božena+Němcová HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz
Content-Length: 0
{
    "title": "Božena Němcová",
    "subtitle": null,
    "type": "",
    "id": "K9MwxcprTo2daXoKxvMHWw",
    "result": {
        "totalElements": 1,
        "duration": 138,
        "content": [
            {
                "name": "Božena Němcová",
                "type": "authority",
                "text": "Božena Němcová",
                "fond": {
                    "id": 31,
                    "name": "Jména osob",
                    "text": "Jména osob"
                },
                "id": "b6d4b384-08f8-4e7b-8497-13e76893985d",
                "kindedId": 191470,
                "status": {
                    "id": 13,
                    "text": "Vlastní autorita"
                },
                "lastUpdateDate": "2020-09-06T15:43:24+02:00",
                "cover": null,
                "directoryId": 282021
            }
        ],
        "numberOfElements": 1,
        "totalPages": 1,
        "pageNumber": 1,
        "pageSize": 30
    }
}

6. Newest documents

Standalone endpoint for fetching newest documents (showing on portaro home page)

6.1. Example

Example 200

GET /api/newest-documents HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz
Content-Length: 0
[
    {
        "id": "25a8d5a6-40aa-49ce-83a6-e7eccb185e9a",
        "kindedId": 923444,
        "name": "Chlorid sodný",
        "type": "document",
        "fond": {"id": 1, "name": "Monografie"},
        "author": "Adler-Olsen, Jussi,",
        "isbn": {
            "value": "9788027511587",
            "trimmedValue": "9788027511587"
        },
        "publisher": "Brno : Host, 2022",
        "publicationYear": 2022,
        "cover": {"id": 427344},
        "fields": [],
        "text": "Chlorid sodný"
    }
]

7. Record resource

7.1. Insert or update record field value

For a quick insert or update single record field value, use /api/records endpoint

/api/records/{recordId}/fields/{fieldId}/fields/{subfieldId}

where

  • recordId is record uuid, e.g. 517458e6-0a48-4af0-a33f-4089f87ccfda

  • fieldId is field uuid

  • subfieldId is subfield uuid

  • request body is json with value to set in value field

Example 200

Set textual value - specify string value

POST /api/records/517458e6-0a48-4af0-a33f-4089f87ccfda/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b  HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value":"Headway"
}

Example 200

Set another record value - specify uuid of record (currently record.id value)

POST /api/records/517458e6-0a48-4af0-a33f-4089f87ccfda/fields/d3170435-5650-4eec-83ea-32830683d531/4c76bed8-e59e-411b-9457-ae49bd9c5e56  HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value":{
    "id":"fb8f6957-f17b-4f09-86e1-bdfdfd7519b8"
  }
}

8. Record editation resource

For a complex manipulation with record, use /api/record-editations endpoint. Firstly, create an record editation for easy fields manipulation. Then, you can add or remove new fields, add or edit field values. Each field gets own unique id. With this id you can address any of field.

8.1. Create record editation

Creates new editation session with given record

GET /api/record-editations/new?kind={kind}&fond={fond}&revisionSavingPolicy={revisionSavingPolicy}&emptyFieldsCompletion={emptyFieldsCompletion}

where

  • kind is type of record: document or authority

  • fond is id of desired record fond, e.g. 1 or 53

  • revisionSavingPolicy is policy, when to automaticly save record, possible values are

    • manual-only - system will never save record automatically - after finish editation, you will have to call save or publish

    • after-each-change-when-draft - system will save record after any change, when record is DRAFT (not published), after publish, you will have to call save manually

    • after-each-change-always - system will save record after any change automatically (no need for manual calling save or publish)

  • emptyFieldsCompletion is whether to automatic empty fields creation, true or false, default true

Example 200

POST /api/record-editations/new?kind=document&fond=1&revisionSavingPolicy=manual-only&emptyFieldsCompletion=false HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz
Content-Length: 0
{
  "id": "sP5NmmLPQVqMGG-EMxqecg",
  "text": "",
  "recordId": "1283f867-3ff8-446f-b3a1-e67ce20cd21c",
  "directoryId": 482527,
  "type": "document",
  "draft": false,
  "revisionSaved": true,
  "fond": {
    "id": 1,
    "text": "Monografie"
  },
  "fields": [
    {
      "id": "96ab9ae4-8764-4fca-9a3e-a78a76e85a30",
      "fieldRepetition": 0,
      "ind1": "0",
      "ind2": "0",
      "empty": true,
      "marcId": "245#0",
      "text": "",
      "code": "245",
      "typeId": "D.245",
      "fieldTypeText": "Údaje o názvu",
      "fields": [
        {
          "id": "4cc32a88-4246-409e-8931-850b61db1ceb",
          "value": null,
          "empty": true,
          "marcId": "245#0.a#0",
          "text": "",
          "url": false,
          "ofRecord": false,
          "raw": null,
          "recordId": null,
          "typeId": "D.245.a",
          "code": "a",
          "fieldTypeText": "Název"
        },
        {
          "id": "6324477d-3491-41ec-a77d-01371227611d",
          "value": null,
          "empty": true,
          "marcId": "245#0.b#0",
          "text": "",
          "url": false,
          "ofRecord": false,
          "raw": null,
          "recordId": null,
          "typeId": "D.245.b",
          "code": "b",
          "fieldTypeText": "Další údaje o názvu"
        },
        {
          "id": "e9ee2815-ab07-4b53-a8de-73e701e433b1",
          "value": null,
          "empty": true,
          "marcId": "245#0.c#0",
          "text": "",
          "url": false,
          "ofRecord": false,
          "raw": null,
          "recordId": null,
          "typeId": "D.245.c",
          "code": "c",
          "fieldTypeText": "Údaj o odpovědnosti atd."
        }
      ]
    }
  ]
}

8.2. Create new field

To create a new field, you must specify type of that field

PUT /api/record-editations/{recordEditationId}/fields/{fieldId}?code={fieldTypeCode}

where

  • recordEditationId is record editation, e.g. sP5NmmLPQVqMGG-EMxqecg

  • fieldId is UUIDv4 of newly creating field - generate by yourself, e.g. 6a7da1b6-7958-491a-b95e-149de4ad9f39

  • fieldTypeCode is code of created field type, e.g. 245

Example 200

PUT /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39?code=245 HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

8.3. Create new subfield

To create a new subfield, you must specify a container field and type of that field. If subfield type is complex authority field (same authority covers multiple subfields, e.g. fields 100.a, 100.b, 100.c), use one composite code "main" (virtual composite field 100.main) in place of creating all subfields.

PUT /api/record-editations/{recordEditationId}/fields/{fieldId}/{subfieldId}?code={fieldTypeCode}

where

  • recordEditationId is record editation, e.g. sP5NmmLPQVqMGG-EMxqecg

  • fieldId is parent field uuid

  • subfieldId is UUIDv4 of newly creating subfield - generate by yourself, e.g. 3b5fb94b-2fd1-4922-8257-68bfe29f7c8b

  • fieldTypeCode is code of created subfield type, e.g. a or main

Example 200

Standard text field (code a)

PUT /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b?code=a HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

Complex authority field (code main)

PUT /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b?code=main HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

8.4. Update record field value

Sets new value to given field. When no field with given identifier exists, creates a new field.

Example 200

Standard text field (code a)

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value":"Headway"
}

Simple authority field (code a) by known record - specify its id

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value":{
    "id":"fb8f6957-f17b-4f09-86e1-bdfdfd7519b8"
  }
}

Simple authority field (code a) by unknown record - specify string subfield value

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value": {
    "fieldLabel": "Beletrie"
  }
}

Complex authority field (code main) by known record - specify its id

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value":{
    "id":"fb8f6957-f17b-4f09-86e1-bdfdfd7519b8"
  }
}

Complex authority field (code main) by unknown record - specify values for particular subfield codes (e.g. 100.a, 100.b, 100.c)

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/fields/6a7da1b6-7958-491a-b95e-149de4ad9f39/3b5fb94b-2fd1-4922-8257-68bfe29f7c8b HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "value": {
    "fieldLabels": {
      "D.100.a": "Němcová, Božena",
      "D.100.d": "1820-1862"
    }
  }
}

8.5. Publish record editation

Publish and save finished record editation session

POST /api/record-editations/sP5NmmLPQVqMGG-EMxqecg/publish HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

8.6. Set record catalogization phase

POST /api/records/phase

{
    record: string,
    phase: string
}

where

  • record is record uuid, e.g. 517458e6-0a48-4af0-a33f-4089f87ccfda

  • phase is desired catalogization phase, valid value is one of:

    • STUB - represent status 2

    • CATALOGING - represent status 3

    • CATALOGED - represent status 4

POST /api/records/phase HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "record": "517458e6-0a48-4af0-a33f-4089f87ccfda",
  "phase": "STUB"
}

8.7. Set record to be visible on given department

After record is created, you hava to specify, where it can be visible. So, create record "holding" on given department.

POST /api/record-holdings HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
    "record": "1283f867-3ff8-446f-b3a1-e67ce20cd21c",
    "department": 26
}

Response

{
  "savedObject": {
    "id": "6713191e-f9cc-47a7-9307-7d7cffbb0b44"
  }
}

9. Sync resource

9.1. Sync single user by external-system user identifier

To sync single user

POST /api/sync/user

Response: FinishedUserSyncResponse (subclass of ActionResponse)

FinishedUserSyncResponse:
{
    responseType: "FinishedUserSyncResponse",
    text: string,
    items: ItemSyncResult[]
}

ItemSyncResult:
{
    item?: LabeledIdentified,
    way: string
}

LabeledIdentified:
{
    id: string | number,
    text: string
}

SyncWay:
"CREATE" | "CREATE_DRAFT" | "UPDATE" | "DELETE" | "SKIP"

Example 200

POST /api/sync/user HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "identifier": "ZAM1XYZ"
}
{
    "text": "User synced with identifier ZAM1XYZ",
    "responseType": "FinishedUserSyncResponse",
    "finished": true,
    "items": [{
        "item": {
            "id": 123456,
            "text": "Jessica Alba"
        },
        "way": "CREATE"
    }]
}

9.2. Fetch-only single user by external-system user identifier

To fetch single user

POST /api/sync/user/fetch

Response: FinishedUserFetchResponse (subclass of ActionResponse)

FinishedUserFetchResponse:
{
    responseType: "FinishedUserFetchResponse",
    text: string,
    items: ItemFetchResult[]
}

ItemFetchResult:
{
    item: UserEditationRequest
}

Example 200

POST /api/sync/user/fetch HTTP/1.1
Content-Type: application/json; charset=UTF-8
Host: https://demo.kpsys.cz

{
  "identifier": "ZAM1XYZ"
}
{
  "text": "User sync with identifier SCH0387",
  "responseType": "FinishedUserFetchResponse",
  "finished": true,
  "items": [
    {
      "item": {
        "id": 31230,
        "active": false,
        "readerAccounts": [
          {
            "readerCategory": {
              "id": "IST",
              "text": "Interní-student"
            },
            "cardNumber": "SCH0387",
            "registrationDate": "2021-09-08T00:00:00+02:00",
            "registrationExpirationDate": "9999-12-31T00:00:00+01:00"
          }
        ],
        "editorAccounts": null,
        "emails": [
          {
            "value": "rostislav.schwarz.st@vsb.cz",
            "source": {
              "id": "external-unis",
              "text": "Unis"
            }
          }
        ],
        "phoneNumbers": [
          {
            "value": "+420734281136",
            "smsCapable": true,
            "source": {
              "id": "external-unis",
              "text": "Unis"
            }
          }
        ],
        "addresses": [
          {
            "permanent": true,
            "mailing": true,
            "street": "Peškova 523/12",
            "city": "Olomouc",
            "state": "Česká republika",
            "postalCode": "77900"
          }
        ],
        "username": null,
        "readableDepartments": null,
        "firstName": "Rostislav",
        "lastName": "Schwarz",
        "prefixDegree": null,
        "suffixDegree": null,
        "birthDate": "1988-03-09T00:00:00+01:00",
        "guId": "SCH0387",
        "netId": "SCH0387",
        "openidId": null,
        "bakalariId": "040449B2BC6380",
        "edookitId": null,
        "edupageId": null,
        "jobName": null,
        "jobAddress": null,
        "educationLevel": "FEI / Fakulta elektrotechniky a informatiky",
        "schoolClass": "K / B",
        "identityCardNumber": null,
        "kind": "PERSON"
      }
    }
  ]
}