@Path(value="pitapi") @Produces(value="application/json") public class TypingRESTResource extends Object
ping
method:
$ curl http://localhost/pitapi/ping Hello World
/pid
. If the
identifier contains a slash, this may be percent-encoded, though the
prototype also tolerates path elements in the style of prefix/suffix.$ curl http://localhost/pitapi/pid/1234%2F5678 ... < HTTP/1.1 404 Not Found ... Identifier not registeredA successful request may look like this:
$ curl http://localhost/pitapi/pid/11043.4%2FPITAPI_TEST1 { "values": { "11314.2/2f305c8320611911a9926bb58dfad8c9": { "name": "", "value": "CC-BY" } } }Note how the result does not provide the property's name. To resolve the name, the parameter include_property_name must be set which makes answering the request however more expensive.
/pid
method also supports HEAD requests for quick
checks whether an identifier is registered.
$ curl http://localhost/pitapi/pid/11043.4/PITAPI_TEST1?filter_by_property=11314.2%2F2f305c8320611911a9926bb58dfad8c9Type filtering is similar, but there can also be several type filters in the same request. This emulates a profile functionality where a profile is understood as a combination of several types: all properties are returned that are specified in any of the types (the selection is thus additive).
$ curl http://localhost/pitapi/pid/1234/5678?filter_by_type=my%2Ftype_1&filter_by_type=my%2Ftype_2 { "values": { "11314.2/2f305c8320611911a9926bb58dfad8c9": { "name": "", "value": "CC-BY" } } "conformance": { "my/type1": true, "my/type2": false } }Overview of all supported parameters for the
/pid
method:
Parameter | Cardinality | Value type | Description |
---|---|---|---|
filter_by_property | 0..1 | Identifier | Filter by given property. |
filter_by_type | 0..n | Identifier | Filter by given type(s). Also includes conformance information. |
include_property_names | 0..1 | Boolean | If true, the method also provies property names along identifiers and values. This is mostly useful for interfaces targeting human end-users. Note that this call comes at additional costs because the property definitions must be retrieved from the type registry. |
/property
method:
$ curl http://localhost/pitapi/property/11314.2/2f305c8320611911a9926bb58dfad8c9 { "identifier": "11314.2/2f305c8320611911a9926bb58dfad8c9", "name": "License", "range": "STRING", "namespace": "RDA", "description": "License information for a digital object." }A similar call exists with the
/type
method for type
definitions.
/peek
method and then use one of the more
specific methods (/pid
, /property
, /type
). The alternative is to use the
/generic
method.
Key | Cardinality | Value |
---|---|---|
PIT_CONSTRUCT | 1 | PROPERTY_DEFINITION |
RANGE | 1 | The range (value type) of the property. Example: STRING |
NAMESPACE | 1 | The namespace of the property. This should be used to distinguish different usage scenarios from each other, e.g. different community understandings. |
Key | Cardinality | Value |
---|---|---|
PIT_CONSTRUCT | 1 | TYPE_DEFINITION |
PROPERTY | 0..n | The properties which make up the type. The value must be a JSON snippet
with the registered PID of a property and a mandatory flag. Example: {"id": "11314.2/2f305c8320611911a9926bb58dfad8c9", "mandatory":true} |
Modifier and Type | Field and Description |
---|---|
protected TypingService |
typingService |
Constructor and Description |
---|
TypingRESTResource() |
Modifier and Type | Method and Description |
---|---|
javax.ws.rs.core.Response |
deletePID(String identifier)
DELETE method to delete identifiers.
|
javax.ws.rs.core.Response |
deletePID(String prefix,
String suffix)
Similar to
deletePID(String) but supports native slashes in the
identifier path. |
javax.ws.rs.core.Response |
isPidRegistered(String identifier)
Simple HEAD method to check whether a particular pid is registered.
|
javax.ws.rs.core.Response |
isPidRegistered(String prefix,
String suffix)
Similar to
isPidRegistered(String) but supports native slashes
in the identifier path. |
javax.ws.rs.core.Response |
peekIdentifier(String identifier)
Queries what kind of entity an identifier will point to (generic object,
property, type, ...).
|
javax.ws.rs.core.Response |
peekIdentifier(String prefix,
String suffix)
Similar to
peekIdentifier(String) but supports native slashes in
the identifier path. |
javax.ws.rs.core.Response |
registerPID(Map<String,String> properties)
Generic POST method to create new identifiers.
|
javax.ws.rs.core.Response |
resolveGenericPID(String identifier)
Generic resolution method to read PID records, property or type
definitions.
|
javax.ws.rs.core.Response |
resolveGenericPID(String prefix,
String suffix)
Similar to
resolveGenericPID(String) but supports native slashes
in the identifier path. |
javax.ws.rs.core.Response |
resolvePID(String identifier,
String propertyIdentifier,
List<String> typeIdentifiers,
boolean includePropertyNames)
Sophisticated GET method to return all or some properties of an
identifier.
|
javax.ws.rs.core.Response |
resolvePID(String identifierPrefix,
String identifierSuffix,
String propertyIdentifier,
List<String> typeIdentifiers,
boolean includePropertyNames)
Similar to
resolvePID(String, String, List, boolean) but
supports native slashes in the identifier path. |
javax.ws.rs.core.Response |
resolveProperty(String identifier)
GET method to read the definition of a property from the type registry.
|
javax.ws.rs.core.Response |
resolveProperty(String prefix,
String suffix)
Similar to
resolveProperty(String) but supports native slashes
in the identifier path. |
javax.ws.rs.core.Response |
resolveType(String identifier)
GET method to read the definition of a type from the type registry.
|
javax.ws.rs.core.Response |
resolveType(String prefix,
String suffix)
Similar to
resolveType(String) but supports native slashes in
the identifier path. |
javax.ws.rs.core.Response |
simplePing()
Simple ping method for testing (check whether the API is running etc.).
|
protected TypingService typingService
@GET @Path(value="/ping") public javax.ws.rs.core.Response simplePing()
@GET @Path(value="/generic/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveGenericPID(@PathParam(value="identifier") String identifier) throws IOException
identifier
- an identifier stringIOException
@GET @Path(value="/generic/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveGenericPID(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix) throws IOException
resolveGenericPID(String)
but supports native slashes
in the identifier path.IOException
resolveGenericPID(String)
@HEAD @Path(value="/pid/{identifier}") public javax.ws.rs.core.Response isPidRegistered(@PathParam(value="identifier") String identifier) throws IOException
identifier
- an identifier stringIOException
@HEAD @Path(value="/pid/{prefix}/{suffix}") public javax.ws.rs.core.Response isPidRegistered(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix) throws IOException
isPidRegistered(String)
but supports native slashes
in the identifier path.IOException
isPidRegistered(String)
@GET @Path(value="/peek/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response peekIdentifier(@PathParam(value="identifier") String identifier) throws IOException
EntityClass
for possible return values.identifier
- full identifier nameEntityClass
for details.IOException
EntityClass
@GET @Path(value="/peek/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response peekIdentifier(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix) throws IOException
peekIdentifier(String)
but supports native slashes in
the identifier path.IOException
peekIdentifier(String)
@GET @Path(value="/pid/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response resolvePID(@PathParam(value="identifier") String identifier, @QueryParam(value="filter_by_property")@DefaultValue(value="") String propertyIdentifier, @QueryParam(value="filter_by_type") List<String> typeIdentifiers, @QueryParam(value="include_property_names")@DefaultValue(value="false") boolean includePropertyNames) throws IOException, InconsistentRecordsException
identifier
- full identifier namepropertyIdentifier
- Optional. Cannot be used in combination with the type
parameter. If given, the method returns only the value of the
single property. The identifier must be registered for a
property in the type registry. The method will return 404 if
the PID exists but does not carry the given property.typeIdentifiers
- Optional. Cannot be used in combination with the property
parameter. If given, the method will return all properties
(mandatory and optional) that are specified in the given
type(s) and listed in the identifier's record. The type
parameter must be a list of type identifiers available from
the registry. If an identifier is not known in the registry,
the method will return 404. The result will also include a
boolean value typeConformance that is only true if all
mandatory properties of the type are present in the PID
record.includePropertyNames
- Optional. If set to true, the method will also provide
property names in addition to identifiers. Note that this is
more expensive due to extra requests sent to the type
registry.IOException
- on communication errors with identifier system or type
registryInconsistentRecordsException
- if records in the identifier system and/or type registry are
inconsistent, e.g. use property or type identifiers that are
not registered@GET @Path(value="/pid/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response resolvePID(@PathParam(value="prefix") String identifierPrefix, @PathParam(value="suffix") String identifierSuffix, @QueryParam(value="filter_by_property")@DefaultValue(value="") String propertyIdentifier, @QueryParam(value="filter_by_type") List<String> typeIdentifiers, @QueryParam(value="include_property_names")@DefaultValue(value="false") boolean includePropertyNames) throws IOException, InconsistentRecordsException
resolvePID(String, String, List, boolean)
but
supports native slashes in the identifier path.@GET @Path(value="/property/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveProperty(@PathParam(value="identifier") String identifier) throws IOException
identifier
- the property identifierIOException
@GET @Path(value="/property/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveProperty(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix) throws IOException
resolveProperty(String)
but supports native slashes
in the identifier path.IOException
resolveProperty(String)
@GET @Path(value="/type/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveType(@PathParam(value="identifier") String identifier) throws IOException
identifier
- the type identifierIOException
@GET @Path(value="/type/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response resolveType(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix) throws IOException
resolveType(String)
but supports native slashes in
the identifier path.IOException
resolveType(String)
@POST @Path(value="/pid") @Consumes(value="application/json") @Produces(value="application/json") public javax.ws.rs.core.Response registerPID(Map<String,String> properties)
properties
- a map from string to string, mapping property identifiers to
values.@DELETE @Path(value="/pid/{identifier}") @Produces(value="application/json") public javax.ws.rs.core.Response deletePID(@PathParam(value="identifier") String identifier)
identifier
- full identifier name@DELETE @Path(value="/pid/{prefix}/{suffix}") @Produces(value="application/json") public javax.ws.rs.core.Response deletePID(@PathParam(value="prefix") String prefix, @PathParam(value="suffix") String suffix)
deletePID(String)
but supports native slashes in the
identifier path.deletePID(String)
Copyright © 2014. All rights reserved.