...
This
...
is
...
a
...
comparison
...
of
...
the
...
current
...
...
...
and
...
the
...
proposed
...
...
...
...
.
...
Included
...
in
...
the
...
current
...
REST
...
API
...
are
...
methods
...
newly-implemented
...
for
...
version
...
3.3
...
(but
...
not
...
yet
...
documented)
...
as
...
listed
...
in
...
JIRA
...
issues
...
for
...
3.3.
...
Only
...
those
...
methods
...
in
...
the
...
proposed
...
REST
...
API
...
are
...
included
...
where
...
there
...
is
...
either
...
a
...
correspondence
...
with
...
the
...
current
...
REST
...
API
...
or
...
where
...
the
...
URL
...
syntax
...
is
...
similar
...
(ie
...
may
...
conflict
...
with
...
the
...
current
...
REST
...
API).
...
The
...
corresponding
...
SOAP
...
API
...
and
...
LITE
...
API
...
methods
...
are
...
also
...
included
...
for
...
reference.
...
E&OE
...
-
...
this
...
is
...
a
...
work
...
in
...
progress
...
and
...
would
...
benefit
...
from
...
another
...
pair
...
of
...
eyes
...
to
...
cross-check...
...
SOAP |
|---|
...
API | Current REST API | verb | Proposed REST API | verb | Notes | LITE API | verb |
|---|---|---|---|---|---|---|---|
findObjects | /objects | GET |
|
| (1) | /search | GET |
resumeFindObjects | /objects | GET |
|
| (1) | /search?sessionToken= |
...
{sessionid} |
...
GET | |
ingest | /objects/ |
...
{pid} |
...
POST |
|
| (2) |
|
| ||
(create empty object) |
|
| /objects | POST |
|
|
|
(create empty object with given pid) |
|
| /objects/{pid} | PUT |
|
|
|
purgeObject | /objects/{pid} | DELETE | /objects/{pid} | DELETE |
|
|
|
getObjectProfile | /objects/{pid} | GET | /objects/{pid}/properties | GET | (4)'(5) |
...
/get/ |
...
{pid} |
...
GET | |
modifyObject | /objects/ |
...
{pid}? |
...
{properties |
...
to |
...
modify} |
...
PUT | /objects/ |
...
{pid}/properties/property |
...
PUT | (3) |
...
|
| |
listDatastreams | /objects/ |
...
{pid}/datastreams |
...
GET |
|
| (1) |
...
/listDatastreams/ |
...
{pid} |
...
[/ |
...
{dateTime} |
...
| GET |
purgeDatastream | /objects/ |
...
{pid}/datastreams/ |
...
{dsid} |
...
DELETE | /objects/ |
...
{pid}/datastreams/ |
...
{dsid} |
...
DELETE |
|
|
| |
getDatastream | /objects/ |
...
{pid}/datastreams/ |
...
{dsid} |
...
GET | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/properties |
...
GET | (4)'(5) |
...
|
| |
addDatastream | /objects/ |
...
{pid}/datastreams/ |
...
{dsid} |
...
POST | /objects/ |
...
{pid |
...
{/datastreams/ |
...
{dsid}/ |
...
[withControlGroup/ |
...
{cg} |
...
| PUT | (4) |
|
|
modifyDatastreamByReference | /objects/{pid}/datastreams/ |
...
{dsid} |
...
PUT | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/properties/contentLocation |
...
PUT | (4)'(6) |
...
|
| |
setDatastreamState | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}?dsState= |
...
{state} |
...
PUT | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/properties/ |
...
{property} |
...
PUT | (3) |
...
|
| |
setDatastreamVersionable | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}?versionable= |
...
{true |
...
| |
...
false} |
...
PUT | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/properties/ |
...
{property} |
...
PUT | (3) |
...
|
| |
getDatastreamDissemination | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/content |
...
GET | /objects/ |
...
{pid}/datastreams/ |
...
{dsid} |
...
GET | (3) |
...
/get/ |
...
{pid}/ |
...
{dsid} |
...
GET | |
getDatastreamDissemination | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/content?asOfDateTime |
...
GET | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}/versions/timestamp/contents |
...
GET | (3)'(7) |
...
/get/ |
...
{pid}/ |
...
{dsid}/ |
...
{dateTime} |
...
GET | |
compareDatastreamChecksum | /objects/ |
...
{pid}/datastreams/ |
...
{dsid}?validateChecksum=true |
...
GET |
|
| (2) |
|
| |
export | /objects/{pid}/export |
...
GET |
|
| (2)'(8) |
...
|
| |
listMethods | /objects/ |
...
{pid}/methods |
...
GET | /objects/ |
...
{pid}/methods |
...
GET |
| /listMethods/ |
...
{pid}/ |
...
{dateTime} |
...
|
...
] |
...
GET | |
(list |
...
methods |
...
in |
...
sdef) |
...
/objects/ |
...
{pid}/methods/ |
...
{sdef} |
...
GET |
|
| (1) |
|
| |
getDissemination | /objects/{pid}/methods/ |
...
{sdef}/ |
...
{method} |
...
GET/POST |
...
/objects/ |
...
{pid}/methods/ |
...
{sdef}/ |
...
{method} |
...
GET/POST |
...
| /get/ |
...
{pid}/ |
...
{sdef}/ |
...
{method} |
...
[/ |
...
{dateTime} |
...
GET | |
getObjectXML | /objects/ |
...
{pid}/objectXML |
...
GET | /objects/ |
...
{pid} |
...
GET | (3)'(8) |
...
|
| |
getObjectHistory | /objects/ |
...
{pid}/versions |
...
GET |
|
| (2)'(7) |
...
/getObjectHistory/ |
...
{pid} |
...
GET | |
getNextPID | /objects/nextPID |
...
POST |
|
| (2) |
...
/management/getNextPID |
...
GET | |||||||
describeRepository |
|
|
|
|
| /describe | GET |
upload |
|
|
|
|
| /management/upload | POST |
getDatastreamHistory |
|
| /objects/{pid}/datastreams/ |
...
{dsid}/versions |
...
GET | (7) |
...
|
| ||||||
getDatastreams |
|
|
|
|
|
|
|
modifyDatastreamByValue |
|
| /objects/{pid}/datastreams/ |
...
{dsid}/contents |
...
PUT |
|
|
|
Notes
(1)
...
Present
...
in
...
current
...
REST
...
API
...
but
...
not
...
in
...
proposed
...
REST
...
API
...
-
...
leave
...
current
...
REST
...
API
...
version
...
as-is,
...
syntax
...
conforms
...
to
...
proposed
...
REST
...
API
...
(2)
...
Present
...
in
...
current
...
REST
...
API
...
but
...
not
...
in
...
proposed
...
REST
...
API
...
-
...
implementation
...
and
...
URL
...
syntax
...
needs
...
defining
...
to
...
conform
...
to
...
proposed
...
REST
...
API
...
(3)
...
Present
...
in
...
both
...
current
...
REST
...
API
...
and
...
proposed
...
REST
...
API
...
but
...
URL
...
syntax
...
differs
...
-
...
proposal:
...
change
...
to
...
use
...
proposed
...
REST
...
API
...
syntax
...
(4)
...
Present
...
in
...
both
...
current
...
REST
...
API
...
and
...
proposed
...
REST
...
API
...
but
...
definition
...
differs
...
-
...
resolution
...
needed
...
(5)
...
Current
...
REST
...
API
...
lists
...
both
...
properties
...
and
...
values;
...
proposed
...
REST
...
API
...
has
...
separate
...
methods
...
for
...
getting
...
a
...
list
...
of
...
properties
...
and
...
getting
...
a
...
property
...
value;
...
to
...
replace
...
current
...
API
...
method
...
both
...
proposed
...
methods
...
need
...
implementing
...
(6)
...
Current
...
REST
...
API
...
includes
...
setting
...
datastream
...
properties
...
as
...
well
...
as
...
updating
...
content;
...
proposed
...
version
...
has
...
different
...
methods
...
for
...
content
...
and
...
properties
...
-
...
to
...
replace
...
current
...
API
...
method
...
both
...
proposed
...
methods
...
need
...
implementing
...
(7)
...
see
...
notes
...
on
...
versions
...
below
...
(8)
...
Difference
...
between
...
"export"
...
and
...
"getObjectXML"
...
needs
...
clarifying
...
in
...
proposed
...
REST
...
API
Versions and History
Versioning describes Versioning in Fedora. Both this and the API documentation talk about retrieving the state of a digital object or datastream at a point in time. Under-the-hood
...
Fedora
...
manages
...
versioning
...
of
...
datastreams
...
by
...
creating
...
copies,
...
versions,
...
with
...
an
...
explicit
...
datastream
...
version
...
identifier
...
and
...
the
...
timestamp
...
of
...
the
...
modification.
...
We
...
have
...
identifiers
...
for
...
objects
...
and
...
datastreams,
...
and
...
the
...
ability
...
to
...
retrieve
...
the
...
state
...
of
...
these
...
objects
...
at
...
a
...
particular
...
time
...
-
...
but
...
so
...
far
...
versions
...
have
...
not
...
really
...
been
...
made
...
explicit
...
as
...
identified
...
resources,
...
rather
...
the
...
ability
...
to
...
retrieve
...
resources
...
as
...
of
...
a
...
point
...
in
...
time
...
has
...
been
...
provided.
...
I
...
think
...
the
...
proposed
...
REST
...
API
...
could
...
be
...
moving
...
away
...
from
...
this
...
(or
...
at
...
least
...
could
...
be
...
ambiguous)
...
by
...
including
...
a
...
timestamp
...
in
...
"version"
...
URLs
...
-
...
The
...
syntax
...
...
...
/versions/
...
{timestamp}
...
...
...
suggests
...
an
...
explicit
...
identifier
...
for
...
a
...
version,
...
rather
...
than
...
identifying
...
the
...
state
...
of
...
the
...
object
...
at
...
a
...
particular
...
time.
...
(Furthermore,
...
if
...
a
...
datastream
...
was
...
modifed
...
at
...
times
...
t1
...
and
...
t2,
...
then
...
URLs
...
including
...
timestamp
...
t
...
such
...
that
...
t1
...
<=
...
t
...
<
...
t2
...
will
...
all
...
retrieve
...
the
...
same
...
content
...
-
...
-
...
effectively
...
there
...
is
...
now
...
a
...
range
...
of
...
URLs
...
for
...
the
...
same
...
"version".)
...
I'd
...
propose
...
that
...
we:
...
1)
...
Standardise
...
on
...
a
...
URL
...
parameter
...
of
...
"asOfDateTime"
...
for
...
all
...
REST
...
API
...
methods
...
to
...
make
...
explicit
...
that
...
it
...
is
...
the
...
state
...
of
...
an
...
object
...
at
...
a
...
particular
...
timepoint
...
that
...
is
...
being
...
referred
...
to
...
(so:
...
GET
...
/objects/
...
{pid}/datastreams/
...
{dsID}?afterDateTime=xyz);
...
or
...
2)
...
Change
...
the
...
"version"
...
component
...
of
...
the
...
URL
...
to
...
"versionAt"
...
(or
...
something
...
similar)
...
to
...
be
...
more
...
explicit.
...
My
...
preference
...
would
...
be
...
for
...
(1).
...
Similarly,
...
I
...
would
...
propose
...
that
...
the
...
methods
...
that
...
retrieve
...
an
...
object's
...
history
...
(URLs
...
ending
...
in
...
/versions)
...
should
...
be
...
made
...
more
...
explicit
...
-
...
in
...
that
...
they
...
are
...
retrieving
...
the
...
points
...
in
...
time
...
that
...
an
...
object
...
was
...
changed,
...
rather
...
than
...
retrieving
...
version
...
identifiers.
...
I
...
would
...
propose
...
changing
...
these
...
URLs
...
to
...
/history.