Skip to content

REST API

Jump to bottom
Moritz Horn edited this page Dec 16, 2024 · 21 revisions

Introduction

The REST API is implemented for the new GOKb Client and covers all needed services to implement the Application as a Single Page Application (SPA).

General

  • request header should contain Accept: application/json
  • add Authorization: Bearer to the request header with the token from login has to be set to use the API - except LOGIN/REGISTER
  • use status code 200 to mark that the operation has been successful, 400 to mark a bad request, 401 for authorization failure
  • use method GET to request a resource, POST to create a resource, PUT/PATCH to update a resource and DELETE to delete a resource implemented methods

LOGIN

Request

POST ./rest/login

Request Payload

{
  "username": "?",
  "password": "?"
}

Response

Status Code: 200
{
  "username": "?",
  "expires_in": 3600,
  "roles":["?"],
  "token_type":"Bearer",
  "access_token": "?",
  "refresh_token": "?"
}

Status Code: 401
-

Refresh

Request

POST ./oauth/access_token

Query String Parameters

grant_type=refresh_token
refresh_token="?"

Response

see LOGIN

Load Profile

Request

GET ./rest/profile

Header Settings

accept : application/json
authorization : Bearer <valid_access_token>

Response

Status Code: 200

{
  "data": {
    "id":?,
    "username":"?",
    "displayName":"?",
    "email":"?",
    "curatoryGroups":[
      {
        "name":"?",
        "id":<db-id>,
        "uuid":"?"
      }
    ],
    "enabled":true,
    "accountExpired":false,
    "accountLocked":false,
    "passwordExpired":false,
    "defaultPageSize":40,
    "roles":[
      {"id": <db-id>,"authority":"ROLE_USER"},
      ...
    ],
    "_links":{
      "self":{
        "href":"https://gokb.org/gokb/rest/profile"
      },
      "update":{
        "href":"https://gokb.org/gokb/rest/profile"
      },
      "delete":{
        "href":"https://gokb.org/gokb/rest/profile"
      }
    }
  }
}

Update Profile

Request

PUT ./home/profile/<id>

Header Settings

accept : application/json
authorization : Bearer <valid_access_token>

Request Payload

{
  "email": "?",
  "password": "?",
  "new_password": "?"
}

Response

Status Code: 200

{
  "data": {
    "id":?,
    "username":"?",
    "displayName":"?",
    "email":"?",
    "curatoryGroups":[
      {
        "name":"?",
        "id":<db-id>,
        "uuid":"?"
      }
    ],
    "enabled":<false|true>,
    "accountExpired":<false|true>,
    "accountLocked":<false|true>,
    "passwordExpired":<false|true>,
    "defaultPageSize":40,
    "roles":[
      {"id": <db-id>,"authority":"ROLE_USER"},
      ...
    ],
    "_links":{
      "self":{
        "href":"https://gokb.org/gokb/rest/profile"
      },
      "update":{
        "href":"https://gokb.org/gokb/rest/profile"
      },
      "delete":{
        "href":"https://gokb.org/gokb/rest/profile"
      }
    }
  }
}

Load User

Request

GET ./rest/users/<id>

Header Settings

accept : application/json
authorization : Bearer <valid_access_token> (needs ROLE_ADMIN)

Response

Status Code: 200

{
  "data": {
    "id":<db-id>,
    "username":"...",
    "displayName":"...",
    "email":"?",
    "curatoryGroups":[
      {
        "name":"...",
        "id":<db-id>,
        "uuid":"<uuid>"
      }
    ],
    "enabled":<false|true>,
    "accountExpired":<false|true>,
    "accountLocked":<false|true>,
    "passwordExpired":<false|true>,
    "defaultPageSize":40,
    "roles":[
      {"id": <db-id>,"authority":"ROLE_USER"},
      ...
    ],
    "_links":{
      "self":{
        "href":"https://gokb.org/gokb/rest/users/..."
      },
      "update":{
        "href":"https://gokb.org/gokb/rest/users/..."
      },
      "delete":{
        "href":"https://gokb.org/gokb/rest/users/..."
      }
    }
  }
}

Create User

Request

POST ./rest/users

Header Settings

accept : application/json
authorization : Bearer <valid_access_token> (needs ROLE_ADMIN)

Request Payload

{
  "username": "...",
  "password": "...",
  "email": "...",
  "accountLocked": <true|false>,
  "enabled": <true|false>,
  "passwordExpired": <true|false>,
  "roleIds": [<db-id>, ...],
  "curatoryGroupIds": [<db-id>, ...],
}

Response

Status Code: 201
Location: ./rest/users/<id>

Update User

Request

PUT ./rest/users/<id>

Header Settings

accept : application/json
authorization : Bearer <valid_access_token> (needs ROLE_ADMIN)

Request Payload

{
  "username": "...",
  "email": "...",
  "accountLocked": <true|false>,
  "enabled": <true|false>,
  "passwordExpired": <true|false>,
  "roleIds": [<db-id>, ...],
  "curatoryGroupIds": [<db-id>, ...],
}

Response

Status Code: 200

{
  "data": {
    "id":?,
    "username":"?",
    "displayName":"?",
    "email":"?",
    "curatoryGroups":[
      {
        "name":"?",
        "id":<db-id>,
        "uuid":"?"
      }
    ],
    "enabled":<false|true>,
    "accountExpired":<false|true>,
    "accountLocked":<false|true>,
    "passwordExpired":<false|true>,
    "defaultPageSize":40,
    "roles":[
      {"id": <db-id>,"authority":"ROLE_USER"},
      ...
    ],
    "_links":{
      "self":{
        "href":"https://gokb.org/gokb/rest/users/..."
      },
      "update":{
        "href":"https://gokb.org/gokb/rest/users/..."
      },
      "delete":{
        "href":"https://gokb.org/gokb/rest/users/..."
      }
    }
  }
}

Load Package

Request

GET ./rest/packages/<id>

Response

Status Code: 200

{
  "_links":{
    "self":{
      "href":"https://gokb.org/gokb/rest/packages/43567426"
    },
    "update": {
      "href":"https://gokb.org/gokb/rest/packages/43567426"
    },
    "delete":{
      "href":"https://gokb.org/gokb/rest/packages/43567426"
    },
    "retire":{
      "href":"https://gokb.org/gokb/rest/packages/43567426/retire"
    }
  },
  "type":"Package",
  "_embedded":{
    "additionalProperties":[],
    "variantNames":[],
    "reviewRequests":[],
    "prices":[],
    "subjects":[],
    "ids":[
      {
        "id":<db-id>,
        "uuid":"<db-uuid>",
        "version":"?",
        "value":"?",
        "namespace":{
          "name":"?",
          "type":"Identifier Namespace",
          "id":?,
          "value":"?"
        },
        "language":null
      }
    ],
    "curatoryGroups":[
      {
        "_links":{
          "self":{
            "href":"https://gokb.org/gokb/rest/curatoryGroups/<db-id>"
          },
          "update":{
            "href":"https://gokb.org/gokb/rest/curatoryGroups/<db-id>"
          },
          "delete":{
            "href":"https://gokb.org/gokb/rest/curatoryGroups/<db-id>"
          },
          "retire":{
            "href":"https://gokb.org/gokb/rest/curatoryGroups/<db-id>/retire"
          }
        },
        "type":null,
        "id":<db-id>,
        "dateCreated":"<timestamp>",
        "uuid":"<db-uuid>",
        "version":"?",
        "superordinatedGroup":null,
        "name":"?",
        "editStatus": {
          "name":"<Approved|In Progress|Rejected>",
          "type":"Refdata Value",
          "id":<db-id>
        },
        "lastUpdated":"<timestamp>",
        "language":null,
        "source":null,
        "status":{
          "name":"<Current|Retired|Expected|Deleted>",
          "type":"Refdata Value",
          "id":<db-id>
        },
        "organizationType":{
          "name":"<Library|Provider|Consortium>",
          "type":"Refdata Value",
          "id":<db-id>
        },
        "description":null,
        "email":"?"
      }
    ]
  },
  "id":<db-id>,
  "dateCreated":"<timestamp>",
  "paymentType":{
    "name":"<Paid|Free|Unknown>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "uuid":"<db-uuid>",
  "consistent":{
    "name":"<Yes|No|Unknown>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "version":"?",
  "lastCachedDate":"<timestamp>",
  "name":"?",
  "breakable":{
    "name":"<Yes|No|Unknown>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "contentType":{
    "name":"<Journal|Book|Database|Mixed>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "descriptionURL":"?",
  "editStatus":{
    "name":"<Approved|In Progress|Rejected>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "listVerifier":<db-id>,
  "listVerifiedDate":<date>,
  "lastUpdated":"<timestamp>",
  "fixed":{
    "name":"<Yes|No|Unknown>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "language":,
  "source":{
    "name":"?",
    "type":"Source",
    "id":<db-id>
  },
  "listStatus":{
    "name":"<Checked|In Progress>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "globalNote":"?",
  "global":{
    "name":"<Global|Consortium|Regional|Local>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "scope":{
    "name":"<Front File|Back File|Aggregator|Master File>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "status":{
    "name":"<Current|Retired|Expected|Deleted>",
    "type":"Refdata Value",
    "id":<db-id>
  },
  "description":"?",
  "provider":{
    "id":<db-id>,
    "name":"?",
    "type":"Organization",
    "uuid":"<db-uuid>"
  },
  "nominalPlatform":{
    "id":<db-id>,
    "name":"?",
    "type":"Platform",
    "uuid":"<db-uuid>"
  },
  "_tippCount":?
}

Create Package

Request

POST ./rest/packages

Header Settings

accept : application/json
authorization : Bearer <valid_access_token> (needs ROLE_EDITOR)

Request Payload

{
  "id": <db-id>,
  "name": "?",
  "source": <db-id>,
  "status": <db-id>,
  "descriptionURL": "...",
  "description":  "...",
  "scope":  <db-id>,
  "global":  <db-id>,
  "globalNote":  "...",
  "contentType":  <db-id>,
  "consistent":  <db-id>,
  "breakable": <db-id>,
  "fixed": <db-id>,
  "subjects": [],
  "listStatus": <db-id>,
  "editStatus": <db-id>,
  "ids": [],
  "provider": <db-id>,
  "nominalPlatform": <db-id>,
}

Response

Status Code: 201
Location: ./rest/packages/<id>

Update Package

Request

PUT ./rest/packages/<id>

Request Payload

Response

Status Code: 200

Load Identifier

Request

GET ./rest/identifiers/<id>

Response

Status Code: 200

Create Identifier

Request

POST ./rest/identifiers

Request Payload

Response

Status Code: 201
Location: ./rest/identifiers/<id>

Update Identifier

Request

PUT ./rest/identifiers/<id>

Request Payload

Response

Status Code: 200

Provider Platform Title Package TitleInstancePackagePlatform (TIPP) Review Curatory Group

Clone this wiki locally