/api/v1/publish
Record publishings of fylr objects in external systems. fylr has no publishing layer of its own — the publication itself (for example a DataCite DOI, an external gallery page or a share link) is produced and hosted elsewhere. A publish entry is fylr's record of such a publication: it ties an object's system_object_id to the collector it was published through (a target configured in the base config, e.g. datacite) and to the external publish_uri where the publication lives, plus a deep-link back into fylr (easydb_uri). These endpoints create, list and delete those records — they do not generate or serve the published artifacts.
GET /publish — List publish records.
Requires the system.api.publish[get] system right.
Access token in the Authorization header:
Authorization: Bearer <token>.
Array of publish descriptors.
A publish record — fylr's note that an object was published in an external system. fylr does not produce or host the publication itself; this entry links the object to the collector it was published through and to the external URL where the publication lives.
Fixed marker identifying this object as a publish.
UTC time the publish entry was created.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the per-operation system right
(system.api.publish[post], system.api.publish[get], or
system.api.publish[delete]).
[
{
"_basetype": "publish",
"publish": {
"system_object_id": 1,
"_id": 1,
"publish_uri": "co456-9885",
"collector": "datacite",
"easydb_uri": "/api/objects/UUID/8"
}
}
]POST /publish — Record one or more publishings.
The payload is an array of publish descriptors. Requires the
system.api.publish[post] system right and a non-read-only
instance.
A descriptor that carries an existing _id updates that
publish row in place; a descriptor without _id (or with _id
0) inserts a new one. Both kinds may be mixed in one request.
Differs from easydb 5: easydb 5 documents this endpoint as
insert-only — "Only new publishing can be done using this API.
There is no possibility to update an existing objects." (DELETE +
re-POST is the documented way to change a publication there). fylr
additionally updates the existing row when a descriptor's _id is
set.
Access token in the Authorization header:
Authorization: Bearer <token>.
A publish record — fylr's note that an object was published in an external system. fylr does not produce or host the publication itself; this entry links the object to the collector it was published through and to the external URL where the publication lives.
Fixed marker identifying this object as a publish.
UTC time the publish entry was created.
The created publish entries.
A publish record — fylr's note that an object was published in an external system. fylr does not produce or host the publication itself; this entry links the object to the collector it was published through and to the external URL where the publication lives.
Fixed marker identifying this object as a publish.
UTC time the publish entry was created.
The publication could not be created. When a descriptor is
invalid the code is PublishUnknownCollector,
PublishInvalidData or PublishDeletedObject
(package: object). A read-only instance rejects the request
with ReadOnlyMode (this check runs before the rights check);
a request body that is not a valid JSON array of descriptors
fails with ServerGeneric.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the per-operation system right
(system.api.publish[post], system.api.publish[get], or
system.api.publish[delete]).
An object referenced by a publish entry's system_object_id
could not be loaded from the object store — on POST the id
in the payload, on DELETE the target object of the publish
row being removed (e.g. the object was hard-deleted after the
publish was recorded). Code ObjectNotFound
(package: ferrors, statuscode: 404), message
Object #<system_object_id> was not found. Not raised by an
unknown id in the request URL — a single GET or a DELETE
for an unknown publish id returns 200, not 404.
[
{
"_basetype": "publish",
"publish": {
"system_object_id": 1,
"_id": 1,
"publish_uri": "co456-9885",
"collector": "datacite",
"easydb_uri": "/api/objects/UUID/8"
}
}
]GET /publish/{systemObjectId} — Retrieve a single publish record by its id.
The path parameter is named systemObjectId in the route for
historical reasons; in fact the value is the publish entry's
own id. The handler returns a single-element array (or an
empty array if no publish has that id). Requires
system.api.publish[get].
Access token in the Authorization header:
Authorization: Bearer <token>.
Publish entry id (not the system_object_id of an object).
Array of zero-or-one publish entries that match the id. An
id matching no stored entry yields an empty array with 200,
not a 404.
A publish record — fylr's note that an object was published in an external system. fylr does not produce or host the publication itself; this entry links the object to the collector it was published through and to the external URL where the publication lives.
Fixed marker identifying this object as a publish.
UTC time the publish entry was created.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the per-operation system right
(system.api.publish[post], system.api.publish[get], or
system.api.publish[delete]).
[
{
"_basetype": "publish",
"publish": {
"system_object_id": 1,
"_id": 1,
"publish_uri": "co456-9885",
"collector": "datacite",
"easydb_uri": "/api/objects/UUID/8"
}
}
]DELETE /publish/{publishId} — Delete a publish record.
Deletes the publish entry with the given _id. Requires the
system.api.publish[delete] system right and a non-read-only
instance. Deleting an unknown publish id is a no-op that still
returns 200 with {"status":{"acknowledged":"ok"}}.
Access token in the Authorization header:
Authorization: Bearer <token>.
The publish entry's _id.
The publication was deleted (or the id did not exist — the delete is a no-op in that case).
The instance is in read-only mode, so no publication can
be deleted. Code ReadOnlyMode (package: ferrors), message
Read-only mode is enabled. This check runs before the
rights check.
No authenticated user. The request must carry a valid access token.
The authenticated user lacks the per-operation system right
(system.api.publish[post], system.api.publish[get], or
system.api.publish[delete]).
An object referenced by a publish entry's system_object_id
could not be loaded from the object store — on POST the id
in the payload, on DELETE the target object of the publish
row being removed (e.g. the object was hard-deleted after the
publish was recorded). Code ObjectNotFound
(package: ferrors, statuscode: 404), message
Object #<system_object_id> was not found. Not raised by an
unknown id in the request URL — a single GET or a DELETE
for an unknown publish id returns 200, not 404.
{
"status": {
"acknowledged": "ok"
}
}Last updated