Differences between revisions 6 and 67 (spanning 61 versions)

Fedora 3.0 API

DOMS metadata objects will be stored in Fedora-commons 3.0.

The API is documented here, as far as it goes: http://www.fedora-commons.org/documentation/3.0/userdocs/index.html#webservices

The structures below are used by Fedora, almost no matter which lanquage you use to interact with it. We use our own shorthand to specify the types. This schema should help you translate to your language of choise

shorthand	wsdl	fedora java client	rest
`String`	xsd:string	java.lang.String	xsd:string
`[]`	xsd:sequence	java array	?
`byte[]`	xsd:base64Binary	jave primitive byte[]	?
`long`	xsd:long	java primitive long	xsd:long
`boolean`	xsd:boolean	java primitive boolean	xsd:boolean

The "fedora-types:ArrayOfString" is defined thus

<complexType name="ArrayOfString">
   <sequence>
      <element name="item" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
   </sequence>
</complexType>

The API to Fedora is directly exported as the primary API to DOMS. We have restricted a few methods, and have some conventions about certain other should be used.

API restrictions

apiM.PurgeDatastream andapiM.PurgeObject are not allowed. Instead use apiM.modifyDatastream and apiM.modifyObject to change the state to "D" (deleted).
apiM.setDatastreamVersionable is disallowed. The internal datastreams are always versioned.
Do not use getNextPID, instead use the method provided from DOMS

Fedora has the concept of state for all objects. We have added additional meaning to this term, which is described in FedoraState. Basically, an object can be Active, Inactive or Deleted. If it is Active, the only allowed change is to make it Inactive. All other attempted changes will throw exceptions. If Inactive, all changes are allowed. Changing the state from anything to Active will cause the object to be validated, and if the object is not valid, the state will not be changed.

Best practice, when perfoming changes in a set of objects it to mark each of them as Inactive, before performing any changes, and perform all changes before moving any of them back to Active.

The Fedora API is described in the the pages below.

The public Access API - Everybody can use this, this is the primary way for external applications to query the repository.
The protected Management API - Only authenticated administrators, such as users of the GUI, can use this.
The Resource Index API - The interface to the Fedora triple store.

-  ⇤ ← Revision 6 as of 2008-09-30 10:53:41 → 
  Size: 5393
  Editor: jrg
  Comment:
+   ← Revision 67 as of 2010-03-17 13:12:49 → ⇥
  Size: 2971
  Editor: localhost
  Comment: converted to 1.6 markup
-Deletions are marked like this.
+Additions are marked like this.
 Line 3:
-DOMS metadata objects will be stored in Fedora-commons 3.0. Fedora 3.0 is currently in beta 2, but is expected to be final by the time we release DOMS.

The API is documented here: http://www.fedora-commons.org/documentation/3.0/userdocs/index.html#webservices

The following restrictions apply:

 * The possibilities "PurgeDatastream" and "PurgeObject" are not allowed. Instead change the state to deleted
 * setDatastreamVersionable is disallowed. The internal datastreams are always versioned.
 * Do not use getNextPID, instead use the method provided from DOMS

All ingested objects, and all updates, must lead to valid objects, as defined by the data model. The exception is that objects marked as "draft" or "intermediate" in the datamodel are always considered valid.

Making a call to any API method that changes the object to a state not valid as defined by the datamodel will fail. Any call to a state-changing API-call where the object is not first set to intermediate state will fail.

== Examples ==

=== Saving seven new interrelated objects to DOMS ===


Since the datamodel may require that all seven objects are correctly ingested and interrelated before they are valid, ingest all seven objects in intermediate state, and then publish them

 * Call the method for generating DOMS PIDs seven times
 * Generate 7 FoxML objects, each with the administrative state set to "intermediate"
 * Call API-M {{{ingest}}} seven times
 * Call API-M {{{modifyDatastreamByValue}}} 7 times to update the state to "published"

=== Updating fields and references for 8 interrelated objects ===

To make sure that the changes don't interfere with validity, first set the state to intermediate, then update state to published after modifications.

 * Call API-M {{{modifyDatastreamByValue}}} 8 times to update the administrative state to "intermediate"
 * Update datastreams and relations as needed to make the changes using {{{addRelationsship}}}/{{{addDatastream}}}/{{{purgeRelationship}}}/{{{modifyDatastreamByValue}}}/{{{setDatastreamState}}}
 * Call API-M {{{modifyDatastreamByValue}}} 8 times to update the administrative state to "published"


== Usage of Fedora API-M and API-A ==

The following describes those methods of the Fedora API-M and API-A that may be called by the GUI.

Descriptions in the following were copied from the Fedora documentation at http://www.fedora-commons.org/confluence/display/FCR30/API-M.

=== API-M ===

==== addDatastream ====

Input parameters:
 * {{{String pid}}} The PID of the object.
 * {{{String dsID}}} The datastream ID (64 characters max). If null, Fedora will generate the value.
 * {{{String[] altIDs}}} Alternate identifiers for the datastream.
 * {{{String dsLabel}}} The label for the datastream.
 * {{{boolean versionable}}} Enable versioning of the datastream.
 * {{{String MIMEType}}} The mime-type of the datastream.
 * {{{String formatURI}}} The format URI of the datastream.
 * {{{String dsLocation}}} Location of managed or external datastream content.
 * {{{String controlGroup}}} One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced).
 * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive).
 * {{{String checksumType}}} The algorithm used to compute the checksum. One of "DEFAULT", "DISABLED", "MD5", "SHA-1", "SHA-256", "SHA-385", "SHA-512", "HAVAL", "TIGER", "WHIRLPOOL".
 * {{{String checksum}}} The value of the checksum represented as a hexadecimal string.
 * {{{String logMessage}}} A log message.

Returns:
 * {{{String}}} The datastreamID of the newly added datastream.


==== addRelationship ====

Input parameters:
 * {{{String pid}}} The PID of the object.
 * {{{String relationship}}} The predicate.
 * {{{String object}}} The object.
 * {{{boolean isLiteral}}} A boolean value indicating whether the object is a literal.
 * {{{String datatype}}} The datatype of the literal. Optional.

Returns:
 * {{{boolean}}} True if and only if the relationship was added.


==== compareDatastreamChecksum ====

Input parameters:
 * {{{String pid}}} The PID of the object.
 * {{{String dsID}}} The datastream ID.
 * {{{String versionDate}}} A dateTime indicating the version of the datastream to verify. If null, Fedora will use the most recent version.

Returns:
 * {{{String}}} The checksum if there is no difference, a message indicating checksum failure otherwise.


==== getDatastream ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== getDatastreams ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== getRelationships ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== ingest ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== modifyDatastreamByReference ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== modifyDatastreamByValue ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== modifyObject ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== purgeRelationship ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== setDatastreamState ====

Input parameters:
 * {{{}}}

Returns:
 * {{{}}}


==== (export) ====
==== (getDatastreamHistory)? ====
==== (getObjectXML)? ====
+DOMS metadata objects will be stored in Fedora-commons 3.0.
-Line 178:
+Line 7:
-=== API-A ===
+The API is documented here, as far as it goes: http://www.fedora-commons.org/documentation/3.0/userdocs/index.html#webservices


The structures below are used by Fedora, almost no matter which lanquage you use to interact with it. We use our own shorthand to specify the types. This schema should help you translate to your language of choise

|| shorthand || wsdl || fedora java client || rest ||
|| {{{String}}} || xsd:string || java.lang.String || xsd:string ||
|| {{{[]}}} || xsd:sequence || java array || ? ||
|| {{{byte[]}}} || xsd:base64Binary || jave primitive byte[] || ? ||
|| {{{long}}} || xsd:long || java primitive long || xsd:long ||
|| {{{boolean}}} || xsd:boolean || java primitive boolean || xsd:boolean ||

The "fedora-types:!ArrayOfString" is defined thus
{{{
<complexType name="ArrayOfString">
   <sequence>
      <element name="item" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
   </sequence>
</complexType>
}}}


The API to Fedora is directly exported as the primary API to DOMS. We have restricted a few methods, and have some conventions about certain other should be used.


== API restrictions ==

 * [[../Fedora 3.0 API/Management#PurgeDatastream| apiM.PurgeDatastream]] and[[../Fedora 3.0 API/Management#PurgeObject| apiM.PurgeObject]] are not allowed. Instead use [[Fedora 3.0 API/Management#modifyDatastream| apiM.modifyDatastream]] and [[Fedora 3.0 API/Management#modifyObject| apiM.modifyObject]] to change the state to "D" (deleted).
 * [[../Fedora 3.0 API/Management#setDatastreamVersionable| apiM.setDatastreamVersionable]] is disallowed. The internal datastreams are always versioned.
 * Do not use getNextPID, instead use the method provided from DOMS


Fedora has the concept of state for all objects. We have added additional meaning to this term, which is described in FedoraState. Basically, an object can be Active, Inactive or Deleted. If it is Active, the only allowed change is to make it Inactive. All other attempted changes will throw exceptions. If Inactive, all changes are allowed. Changing the state from anything to Active will cause the object to be validated, and if the object is not valid, the state will not be changed.

Best practice, when perfoming changes in a set of objects it to mark each of them as Inactive, before performing any changes, and perform all changes before moving any of them back to Active.

The Fedora API is described in the the pages below.

 * [[../Fedora 3.0 API/Access| The public Access API]] - Everybody can use this, this is the primary way for external applications to query the repository.
 * [[../Fedora 3.0 API/Management| The protected Management API]] - Only authenticated administrators, such as users of the GUI, can use this. 
 * [[Fedora 3.0 triple store API| The Resource Index API]] - The interface to the Fedora triple store.