Skip to content

Getting Started

Registration

To use pid4cat services, organizations must apply to become a Sub-Name Assigning Authority (SNAA). The application process involves:

  1. Submitting an application form to the pid4cat core organization (TODO add contact info)
  2. Agreeing to the pid4cat policies (detailed in section Policies)
  3. Demonstrating the capability to maintain the identified resources
  4. Designating a technical and administrative contact

Upon approval, the organization will receive:

  • A unique namespace suffix (<ns-suffix>)
  • API credentials for accessing the pid4cat API
  • Documentation and support for the integration into SNAA-operated services

Structure of pid4cat handles

A pid4cat handle has the form <prefix>/4cat/<ns-suffix>/<id-suffix>, for example 21.11165/4cat/d4y/sample-001:

  • <prefix>: the Handle prefix.
  • 4cat: a fixed segment that marks pid4cat handles.
  • <ns-suffix>: the namespace of one SNAA, assigned at registration. It has three lower-case characters from the Crockford Base32 alphabet (digits and letters without i, l, o and u): a letter, a digit, then a letter or digit, for example d4y. Some combinations are reserved and never assigned. Test namespaces have the form test-<ns-suffix>.
  • <id-suffix>: the identifier within the namespace. It has 1 to 36 characters from a-z, 0-9, . and -. It contains no /, so every pid4cat handle has exactly four segments.

Handles resolve case-insensitively. Lower case in <ns-suffix> and <id-suffix> gives each handle a single spelling.

Creating identifiers

Identifiers can be created through the pid4cat API. Partner organizations (SNAAs) have two options:

  1. Generated identifiers: Identifiers generated by the pid4cat API
  2. Custom identifiers: Identifiers created according to SNAA's naming conventions

The API URLs are not final.

TODO: Update API urls below before Release 1.0.0.

To request a new identifier generated by pid4cat service:

PUT https://api.nfdi4cat.org/testpid/v2/handles/<prefix>/4cat/<ns-suffix>/

To create a custom identifier: (Future!)

PUT https://api.nfdi4cat.org/testpid/<version>?customid=xxx-xxx

With a payload containing:

  • The <id-suffix> (optional for opaque identifiers)
  • The URL of the resource
  • Required metadata according to the pid4cat-model

For detailed API documentation, see the REST APIs section.

Updating identifiers

Identifiers and their associated metadata can be updated through the pid4cat API:

The API URLs are not final.

TODO: Update API urls below before Release 1.0.0.

PUT https://api.nfdi4cat.org/testpid/v2/handles/<prefix>/4cat/<ns-suffix>/<id-suffix>

Updates may include:

  • Change of the target URL
  • Additions or modifications to metadata

Note that the identifier itself cannot be changed once created. Only its associated metadata and target URL can be modified.

Resolving identifiers

pid4cat identifiers can be resolved using:

  1. Direct resolution: https://hdl.handle.net/<prefix>/4cat/<ns-suffix>/<id-suffix>
  2. pid4cat resolver: https://pid.nfdi4cat.org/<prefix>/4cat/<ns-suffix>/<id-suffix>
  3. pid4cat resolver: https://handle.nfdi4cat.org/<prefix>/4cat/<ns-suffix>/<id-suffix>

Resolution will typically redirect to the landing page for the identified resource, which should be maintained by the responsible SNAA.