{"openapi":"3.1.0","info":{"title":"Typed PID Maker - RESTful API","description":"The Typed PID Maker is a service for creating, updating, obtaining and validating PID record information using Kernel Information Profiles, as defined by the Research Data Alliance.","contact":{"name":"KIT Data Manager Support","url":"https://github.com/kit-data-manager","email":"support@datamanager.kit.edu"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"version":"2.0.0"},"servers":[{"url":"http://typed-pid-maker.datamanager.kit.edu/preview","description":"Generated server url"}],"tags":[{"name":"PID Management","description":"PID Information Types API"},{"name":"Actuator","description":"Monitor and interact","externalDocs":{"description":"Spring Boot Actuator Web API Documentation","url":"https://docs.spring.io/spring-boot/docs/current/actuator-api/html/"}}],"paths":{"/api/v1/pit/pid/**":{"get":{"tags":["PID Management"],"summary":"Get the record of the given PID.","description":"Get the record to the given PID, if it exists. May also be used to test if a PID exists. No validation is performed by default.","operationId":"getRecord","parameters":[{"name":"validation","in":"query","description":"If true, validation will be run on the resolved PID. On failure, an error will be returned. On success, the PID will be resolved.","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"400":{"description":"Validation failed. See body for details.","content":{"application/json":{}}},"200":{"description":"Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIDRecord"}},"application/vnd.datamanager.pid.simple+json":{"schema":{"$ref":"#/components/schemas/SimplePidRecord"}}}},"404":{"description":"Not found","content":{"application/json":{}}},"503":{"description":"Communication to required external service failed.","content":{"application/json":{}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{}}}}},"put":{"tags":["PID Management"],"summary":"Update an existing PID record","description":"Update an existing PID record using the record information from the request body. The record may contain the identifier(s) of the matching profiles. Conditions for a valid record are the same as for creation. Important note: Validation may take some time. For details, see the documentation of \"POST /pid/\".","operationId":"updatePID","parameters":[{"name":"dryrun","in":"query","description":"If true, no PID will be updated. Only validation checks are performed, and the expected response, including the new eTag, will be returned. No data will be changed and no services will be notified.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"description":"The body containing all PID record values as they should be after the update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIDRecord"}},"application/vnd.datamanager.pid.simple+json":{"schema":{"$ref":"#/components/schemas/SimplePidRecord"}}},"required":true},"responses":{"400":{"description":"Validation failed. See body for details.","content":{"application/json":{}}},"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIDRecord"}},"application/vnd.datamanager.pid.simple+json":{"schema":{"$ref":"#/components/schemas/SimplePidRecord"}}}},"406":{"description":"Provided input is invalid with regard to the supported accept header (Not acceptable)","content":{"application/json":{}}},"415":{"description":"Provided input is invalid with regard to the supported content types. (Unsupported Mediatype)","content":{"application/json":{}}},"412":{"description":"ETag comparison failed (Precondition failed)","content":{"application/json":{}}},"428":{"description":"No ETag given in If-Match header (Precondition required)","content":{"application/json":{}}},"503":{"description":"Communication to required external service failed.","content":{"application/json":{}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{}}}}}},"/api/v1/pit/pids":{"post":{"tags":["PID Management"],"summary":"Create a multiple, possibly related PID records","description":"Create multiple, possibly related PID records using the record information. This endpoint is a convenience method to create multiple PID records at once. For connecting records, the PID fields must be specified and the value may be used in the value fields of other PIDRecordEntries. The provided PIDs will be overwritten as defined by the PID generator strategy.\nNote: This endpoint does not support custom PIDs, as the PID field is used for \"placeholder\" PIDs to connect records. These placeholder PIDs will be replaced by actual, resolvable PIDs as defined by the PID generator strategy. This goes for the PID referencing a record as well as references from other records, if they are provided as a single attribute value (i.e., not a JSON array within an attribute's value). If you want to create a record with custom PID suffixes, use the endpoint `POST /pid` and configure the Typed PID Maker accordingly.","operationId":"createPIDs","parameters":[{"name":"dryrun","in":"query","description":"If true, only validation will be done and no PIDs will be created. No data will be changed and no services will be notified.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"description":"The body containing a list of all PID record values as they should be in the new PID records. To connect records, the PID fields must be specified. This placeholder PID value may then be used in the value fields of other PID Record entries. During creation, these placeholder PIDs whose sole purpose is to connect records will be overwritten with actual, resolvable PIDs as defined by the PID generator strategy.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PIDRecord"}}}},"required":true},"responses":{"400":{"description":"Validation failed. See body for details. Contains also the validated records.","content":{"application/json":{}}},"201":{"description":"Successfully created all records and resolved references (if they exist). The response contains the created records and the mapping used to map from the user-provided, placeholder PIDs to the actual Handle PIDs created in the process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRecordResponse"}}}},"406":{"description":"Provided input is invalid with regard to the supported accept header (Not acceptable)","content":{"application/json":{}}},"415":{"description":"Provided input is invalid with regard to the supported content types. (Unsupported Mediatype)","content":{"application/json":{}}},"409":{"description":"If providing own PIDs is enabled 409 indicates, that the PID already exists.","content":{"application/json":{}}},"503":{"description":"Communication to required external service failed.","content":{"application/json":{}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{}}}}}},"/api/v1/pit/pid/":{"post":{"tags":["PID Management"],"summary":"Create a new PID record","description":"Create a new PID record using the record information from the request body. The record may contain the identifier(s) of the matching profile(s). Before creating the record, the record information will be validated against the profile. Validation takes some time, depending on the context. It depends a lot on the size of your record and the already cached information. This information is gathered from external services. If there are connection issues or hiccups at these sites, validation may even take up to a few seconds. Usually you can expect the request to be between 100ms up to 1000ms on a fast machine with reliable connections.","operationId":"createPID","parameters":[{"name":"dryrun","in":"query","description":"If true, only validation will be done and no PID will be created. No data will be changed and no services will be notified.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"description":"The body containing all PID record values as they should be in the new PIDs record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIDRecord"}},"application/vnd.datamanager.pid.simple+json":{"schema":{"$ref":"#/components/schemas/SimplePidRecord"}}},"required":true},"responses":{"400":{"description":"Validation failed. See body for details. Contains also the validated record.","content":{"application/json":{}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIDRecord"}},"application/vnd.datamanager.pid.simple+json":{"schema":{"$ref":"#/components/schemas/SimplePidRecord"}}}},"406":{"description":"Provided input is invalid with regard to the supported accept header (Not acceptable)","content":{"application/json":{}}},"415":{"description":"Provided input is invalid with regard to the supported content types. (Unsupported Mediatype)","content":{"application/json":{}}},"409":{"description":"If providing an own PID is enabled 409 indicates, that the PID already exists.","content":{"application/json":{}}},"503":{"description":"Communication to required external service failed.","content":{"application/json":{}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{}}}}}},"/api/v1/pit/known-pid":{"get":{"tags":["PID Management"],"summary":"Returns all known PIDs. Supports paging, filtering criteria, and different formats.","description":"Returns all known PIDs, limited by the given page size and number. Several filtering criteria are also available. Known PIDs are defined as being stored in a local store. This store is not a cache! Instead, the service remembers every PID which it created (and resolved, depending on the configuration parameter `pit.storage.strategy` of the service) on request. Use the Accept header to adjust the format.","operationId":"findAll","parameters":[{"name":"created_after","in":"query","description":"The UTC time of the earliest creation timestamp of a returned PID.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"The UTC time of the latest creation timestamp of a returned PID.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_after","in":"query","description":"The UTC time of the earliest modification timestamp of a returned PID.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_before","in":"query","description":"The UTC time of the latest modification timestamp of a returned PID.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","description":"Zero-based page index (0..N)","schema":{"type":"integer","default":0}},{"name":"size","in":"query","description":"The size of the page to be returned","schema":{"type":"integer","default":20}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","schema":{"type":"array","items":{"type":"string"}}},{"name":"Accept","in":"header","schema":{"type":"string","enum":["application/tabulator+json"]}}],"responses":{"400":{"description":"Bad Request","content":{"application/hal+json":{"schema":{"type":"object"}}}},"200":{"description":"If the request was valid. May return an empty list.","content":{"application/hal+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KnownPid"}}},"application/tabulator+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TabulatorPaginationFormatKnownPid"},{"$ref":"#/components/schemas/TabulatorPaginationFormat"}]}}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{},"application/tabulator+json":{"schema":{"$ref":"#/components/schemas/TabulatorPaginationFormatKnownPid"}}}}}}},"/api/v1/pit/known-pid/**":{"get":{"tags":["PID Management"],"summary":"Returns a PID and its timestamps from the local store, if available.","description":"Returns a PID from the local store. This store is not a cache! Instead, the service remembers every PID which it created (and resolved, depending on the configuration parameter `pit.storage.strategy` of the service) on request. If this PID is known, it will be returned together with the timestamps of creation and modification executed on this PID by this service.","operationId":"findByPid","responses":{"400":{"description":"Bad Request","content":{"application/hal+json":{"schema":{"type":"object"}}}},"200":{"description":"If the PID is known and its information was returned.","content":{"application/hal+json":{"schema":{"$ref":"#/components/schemas/KnownPid"}}}},"404":{"description":"If the PID is unknown.","content":{"application/json":{}}},"500":{"description":"Server error. See body for details.","content":{"application/json":{}}}}}},"/actuator":{"get":{"tags":["Actuator"],"summary":"Actuator root web endpoint","operationId":"links","responses":{"400":{"description":"Bad Request","content":{"application/hal+json":{"schema":{"type":"object"}}}},"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}},"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}}}}}}},"/actuator/info":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'info'","operationId":"info","responses":{"400":{"description":"Bad Request","content":{"application/hal+json":{"schema":{"type":"object"}}}},"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}}}}},"/actuator/health":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'health'","operationId":"health","responses":{"400":{"description":"Bad Request","content":{"application/hal+json":{"schema":{"type":"object"}}}},"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"PIDRecord":{"type":"object","properties":{"pid":{"type":"string"},"entries":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/PIDRecordEntry"}}}}},"PIDRecordEntry":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}},"SimplePair":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"SimplePidRecord":{"type":"object","properties":{"pid":{"type":"string"},"record":{"type":"array","items":{"$ref":"#/components/schemas/SimplePair"}}}},"BatchRecordResponse":{"type":"object","properties":{"pidRecords":{"type":"array","items":{"$ref":"#/components/schemas/PIDRecord"}},"mapping":{"type":"object","additionalProperties":{"type":"string"}}}},"KnownPid":{"type":"object","properties":{"pid":{"type":"string","minLength":1},"created":{"type":"string","format":"date-time"},"modified":{"type":"string","format":"date-time"}},"required":["created","modified","pid"]},"TabulatorPaginationFormat":{"type":"object","properties":{"data":{"type":"array","items":{}},"last_page":{"type":"integer","format":"int32"}}},"TabulatorPaginationFormatKnownPid":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KnownPid"}},"last_page":{"type":"integer","format":"int32"}}},"Link":{"type":"object","properties":{"href":{"type":"string"},"hreflang":{"type":"string"},"title":{"type":"string"},"type":{"type":"string"},"deprecation":{"type":"string"},"profile":{"type":"string"},"name":{"type":"string"},"templated":{"type":"boolean"}}}},"securitySchemes":{"bearer-jwt":{"type":"http","name":"Authorization","in":"header","scheme":"bearer","bearerFormat":"JWT"}}}}