DataONE PIRI Service
====================

Overview
--------

The DataONE PIRI (Persistent Internationalized Resource Identifier) Service provides canonical and resolveable IRIs (Internationalalized Resource Identifier) for top-level DataONE resources (e.g., datasets, people) in both web and linked open data contexts.
The problem this solves is that DataONE resources can be resolved at a variety of URLs which contain application-, deployment-, and API (Application Programming Interface)-version-specific details.
An IRI space that is agnostic to these details allows resources to be identified and resolved in a stable fashion.

Take, for example, the following IRI, which can be used to resolve the location of the Object with the :doc:`PID <../design/PIDs>` (Persistent Identifier) ``'mydataset'``::

  https://cn.dataone.org/cn/v2/resolve/mydataset

Under the PIRI Service, the above resource has the following PIRI::

  https://dataone.org/datasets/mydataset

This is an improvement because the first IRI leaks application-, deployment-, and API-version-specific information into the IRI.
All of which may change as some point in the future.
With the DataONE PIRI Service (and the IRI space it defines), applications become free to be addressed at different DNS (Domain Name Service) names and APIs are free to change and/or have their versions incremented.
All while references to resources within the network remain resolveable.

Specification
-------------

The DataONE PIRI Service defines an IRI space with the following pattern::

  https://dataone.org/{type}/{id}

Where ``{type}`` is one of:

- ``datasets``
- ``people`` (not implemented)

And ``{id}`` is an appropriate identifier for resource such as a PID or SID (Series Identifier) for the 'datasets' type.
Note that all identifiers should be escaped according to RFC3986_.
See :doc:`../design/PIDs` for more information.

.. _RFC3986: https://tools.ietf.org/html/rfc3986

Implementation
--------------

Requests to URLs (Universal Resource Locator) within the PIRI service's IRI space are redirected with an HTTP 302 status to a corresponding URL within the DataONE search portal.
Future changes to this service may include providing content-negotation and returning information about resources or the resources themselves directly from the PIRI service.

Only URLs under ``https://dataone.org/datasets/`` are supported and are redirected to ``https://search.dataone.org/view/`` by configuration on the web server running at https://dataone.org/.