Skip to content

Commit fcc4f64

Browse files
tomcranetomcrane
committed
move unimplemented adjuncts stuff to scratch file
1 parent 6346f3c commit fcc4f64

2 files changed

Lines changed: 148 additions & 128 deletions

File tree

‎scratch/api-doc/adjuncts.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Adjuncts — scratch notes
2+
3+
## Creating an adjunct by supplying content separately (not yet implemented)
4+
5+
This section was removed from adjuncts.mdx because the content endpoint cannot currently be POSTed to or read from.
6+
7+
The third mechanism creates the API resource for the adjunct, and then supplies the binary content in a separate step. Again, the adjunct can be created by PUT or POST:
8+
9+
```
10+
POST https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts
11+
{
12+
"id": "mets-from-content.xml",
13+
"@type": "Dataset",
14+
"mediaType": "text/xml",
15+
"profile": "http://www.loc.gov/standards/alto/v3/alto.xsd",
16+
"label": { "en": [ "METS-ALTO XML" ] },
17+
"iiifLink": "seeAlso"
18+
}
19+
```
20+
21+
or by PUT (`id` is optional but if present, must match the PUT URL):
22+
23+
```
24+
PUT https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts/mets-from-content.xml
25+
{
26+
"@type": "Dataset",
27+
"mediaType": "text/xml",
28+
"profile": "http://www.loc.gov/standards/alto/v3/alto.xsd",
29+
"label": { "en": [ "METS-ALTO XML" ] },
30+
"iiifLink": "seeAlso"
31+
}
32+
```
33+
34+
In both these cases the response is HTTP 201 Created, and the adjunct API resource is available immediately and looks like this:
35+
36+
```
37+
GET https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts/mets-from-content.xml
38+
```
39+
returns:
40+
41+
```json
42+
{
43+
"@id": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts/mets-from-content.xml",
44+
"@type": "Dataset",
45+
"mediaType": "text/xml",
46+
"profile": "http://www.loc.gov/standards/alto/v3/alto.xsd",
47+
"label": { "en": [ "METS-ALTO XML" ] },
48+
"iiifLink": "seeAlso",
49+
"motivation": null,
50+
"provides": null,
51+
"size": 0,
52+
"ingesting": false,
53+
"error": null,
54+
"created": "2025-09-22T16:49:29+00:00",
55+
"finished": "2025-09-22T16:49:29+00:00",
56+
"roles": [],
57+
"content": "https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts/mets-from-content.xml/content"
58+
}
59+
```
60+
61+
The adjunct has no `publicId` property, and has a `size` of 0.
62+
63+
To change this we need to POST the content to the URL given by the adjunct's `content` property:
64+
65+
```
66+
POST https://api.dlcs.example/customers/2/spaces/5/images/b2921371x_0001.jp2/adjuncts/mets-from-content.xml/content
67+
<binary body>
68+
```
69+
70+
This is a synchronous operation. Requesting the adjunct immediately will result in HTTP 200 OK, but the `ingesting` property is likely to be `true`. Once the POSTed content has been stored and measured and the adjunct record updated, the `ingesting` property will be `false`. Any error encountered will be recorded in the `error` property.
71+
72+
LinkCard: 💻 Create an adjunct by supplying content separately
73+
→ dlcs-docs-client/p13_adjuncts/content_adjunct.py
74+
75+
---
76+
77+
## content field (not yet implemented)
78+
79+
This section was removed from adjuncts.mdx because the content endpoint cannot currently be POSTed to or read from.
80+
81+
`/customers/{customer}/spaces/{space}/images/{assetId}/adjuncts/{adjunctId}/content`
82+
83+
A link to the adjunct content. Assuming the adjunct has been processed, an HTTP GET request will return the same bytes as the `publicId`, but without using any IIIF Auth via roles. If you have an API key to see the API adjunct, the same key will let you access the content at this URL.
84+
85+
The other use of `content` is to _supply_ the bytes of an adjunct, via HTTP POST. If created without an `origin` (or without a creating pipeline specified), the adjunct will have no content and size 0, _until_ the bytes of the adjunct are POSTed to this URL.
86+
87+
---
88+
89+
## No iiifLink / otherAdjuncts (not yet implemented)
90+
91+
Removed from the iiifLink section and the single-asset-manifest examples. When implemented:
92+
93+
- `iiifLink` will accept a no or null value
94+
- Adjuncts without `iiifLink` will appear in a non-standard `otherAdjuncts` property on the Canvas (defined in the single-asset-manifest @context)
95+
- As `otherAdjuncts` is not a valid IIIF property, users should process and remove it when turning platform-generated IIIF into public-facing IIIF
96+
97+
The fifth adjunct in the iiifLink example (before removal):
98+
99+
```json
100+
{
101+
"id": "link-unspecified-from-external.xml",
102+
"externalId": "https://dlcsstage-public-test-objects.s3.eu-west-1.amazonaws.com/images-with-text/b29820947_0014.jp2.xml",
103+
"@type": "Text",
104+
"mediaType": "text/xml",
105+
"label": { "en": [ "A link to a resource without a IIIF expression" ] }
106+
}
107+
```
108+
109+
The corresponding canvas output (before removal):
110+
111+
```jsonc
112+
"otherAdjuncts": [ // new property (defined in single-asset-manifest @context)
113+
{
114+
"id": "https://dlcsstage-public-test-objects.s3.eu-west-1.amazonaws.com/images-with-text/b29820947_0014.jp2.xml",
115+
"type": "Text",
116+
"format": "text/xml",
117+
"label": { "en": ["A link to a resource without a IIIF expression"]}
118+
}
119+
]
120+
```

0 commit comments

Comments
 (0)