Tidy differences from initial docs. Update named queries

dlcs · Jun 9, 2020 · 388f7bf · 388f7bf
1 parent 9590424
commit 388f7bf
Show file tree

Hide file tree

Showing 7 changed files with 29 additions and 107 deletions.
diff --git a/API_Reference/batch.md b/API_Reference/batch.md
@@ -115,44 +115,6 @@ Collection of all the images in the batch
 | GET    | Retrieves all images in batch regardless of state |         | hydra:Collection | 200 OK   |
 
 
-### completedImages (🔗)
-
-Collection of images that have completed processing
-
-
-| domain      | range            | readonly | writeonly |
-|-------------|------------------|----------|-----------|
-| vocab:Batch | hydra:Collection | True     | False     |
-
-
-<!-- call fails -->
-`/customers/{customer}/queue/batches/{batchId}/completedImages`
-
-
-| Method | Label                                   | Expects | Returns          | Statuses |
-|--------|-----------------------------------------|---------|------------------|----------|
-| GET    | Retrieves all COMPLETED images in batch |         | hydra:Collection | 200 OK   |
-
-
-### errorImages (🔗)
-
-Collection of images that encountered errors
-
-
-| domain      | range            | readonly | writeonly |
-|-------------|------------------|----------|-----------|
-| vocab:Batch | hydra:Collection | True     | False     |
-
-
-<!-- call fails -->
-`/customers/{customer}/queue/batches/{batchId}/errorImages`
-
-
-| Method | Label                               | Expects | Returns          | Statuses |
-|--------|-------------------------------------|---------|------------------|----------|
-| GET    | Retrieves all ERROR images in batch |         | hydra:Collection | 200 OK   |
-
-
 ### test (🔗)
 
 POST to this to force an update of the batch's superseded property. Returns JSON object with single success property (boolean). 

diff --git a/API_Reference/image.md b/API_Reference/image.md
@@ -51,9 +51,7 @@ Origin endpoint from where the original image can be acquired (or was acquired)
 
 ### initialOrigin
 
-Endpoint to use the first time the image is retrieved. This allows an initial ingest from a short term s3 bucket (for example) but subsequent references from an https URI.
-
-<!-- is it correct that this is writeonly? -->
+Endpoint to use the first time the image is retrieved. This allows an initial ingest from a short term s3 bucket (for example) but subsequent references from an https URI. This property is only used for ingestion and is not persisted for future use.
 
 
 | domain      | range      | readonly | writeonly |
@@ -221,11 +219,6 @@ The batch this image was ingested in (most recently). Might be blank if the batc
 | vocab:Image | xsd:nonNegativeInteger | True     | False     |
 
 
-### preservedUri
-
-<!-- what does this do? -->
-
-
 ### roles (🔗)
 
 The role, or roles, that a user must possess to view this image above maxUnauthorised. These are URIs of roles e.g., `https://api.dlcs.io/customers/1/roles/requiresRegistration`

diff --git a/API_Reference/namedquery.md b/API_Reference/namedquery.md
@@ -12,6 +12,8 @@ This query is an instance of the following template:
 
 This customer (iiifly) has a named query called 'manifest' that takes two parameters - the space and the string1 metadata field. The query is internally defined to use an additional field - number1 -  and to generate a manifest with one sequence, with each canvas in the sequence having one image. The images selected by the query must all have string1=ae678999 in this case, and are ordered by number1.  An image query against the dlcs API returns a collection of DLCS Image objects. a Named Query uses an DLCS image query but then projects these images and  constructs a IIIF resource from them, using the parameters provided. Information on designing and configuring named queries is provided in a special topic.
 
+See [More on named queries](../More_on_named_queries.md) for further explanation on named queries.
+
 
 <!-- 
 this returns a 500
@@ -63,4 +65,3 @@ URI template
 | domain           | range      | readonly | writeonly |
 |------------------|------------|----------|-----------|
 | vocab:NamedQuery | xsd:string | False    | False     |
-
diff --git a/API_Reference/portaluser.md b/API_Reference/portaluser.md
@@ -69,17 +69,6 @@ Collection of Role resources that the user has. These roles should not be confus
 | vocab:PortalUser | hydra:Collection | True     | False     |
 
 
-`/customers/{customer}/portalUsers/{roleId}/roles`
-
-
-| Method | Label                     | Expects          | Returns          | Statuses                                  |
-|--------|---------------------------|------------------|------------------|-------------------------------------------|
-| GET    | Retrieves all Portal Role |                  | hydra:Collection | 200 OK                                    |
-| POST   | Creates a new Portal Role | vocab:PortalRole | vocab:PortalRole | 201 Portal Role created., 400 Bad Request |
-
-<!-- returns 500 -->
-
-
 ### enabled
 
 Whether the user can log in - for temporary or permanent rescinding of access.

diff --git a/API_Reference/querying_for_images.md b/API_Reference/querying_for_images.md
@@ -4,8 +4,6 @@ Any hyperlink to a collection of images can accept query parameters that filter
 
 * space.images (`/customer/{customer}/space/{spaceId}/images?string1=bib343434`)
 
-<!-- only works for space.images -->
-
 Once you have registered images with the DLCS you can query it for information on them. One immediate use of this is to monitor the progress of ongoing registrations. For example, if you registered a batch of 100,000 images it will take some time for the DLCS to process them, and you would like to be able to monitor progress and view any errors that were encountered. You can also query for usage statistics.
 
 You issue a DLCS query by submitting parameters that match the metadata fields, or a serialised JSON query object. This is a pattern for the DLCS to match metadata fields on. The model is very similar to the image registration data model, except you are submitting a filter and expecting all images that match that filter to be returned.

diff --git a/API_Reference/space.md b/API_Reference/space.md
@@ -57,50 +57,6 @@ Default tags to apply to images created in this space
 | vocab:Space | xsd:string | False    | False     |
 
 
-### maxUnauthorised
-
-Default size at which role-based authorisation will be enforced. -1=open, 0=always require auth
-
-
-| domain      | range       | readonly | writeonly |
-|-------------|-------------|----------|-----------|
-| vocab:Space | xsd:integer | False    | False     |
-
-
-### approximateNumberOfImages
-
-Rough total of number of images in space
-
-| domain      | range       | readonly | writeonly |
-|-------------|-------------|----------|-----------|
-| vocab:Space | xsd:integer | False    | False     |
-
-
-### keep
-
-| domain      | range       | readonly | writeonly |
-|-------------|-------------|----------|-----------|
-| vocab:Space | xsd:boolean | False    | False     |
-
-<!-- what does this do? -->
-
-
-### transform
-
-| domain      | range       | readonly | writeonly |
-|-------------|-------------|----------|-----------|
-| vocab:Space | xsd:boolean | False    | False     |
-
-<!-- what does this do? -->
-
-### imageBucket
-
-| domain      | range       | readonly | writeonly |
-|-------------|-------------|----------|-----------|
-| vocab:Space | xsd:string  | False    | False     |
-
-<!-- what does this do? -->
-
 ### defaultRoles (🔗)
 
 Default roles that will be applied to images in this space

diff --git a/More_on_named_queries.md b/More_on_named_queries.md
@@ -1,18 +1,41 @@
 # More on Named Queries
 
-An example of Named Queries is their user by the iiif.ly application to generate a manifest from a set of images.
+An example of Named Queries is their user by the iiif.ly application to generate a manifest from a set of images.   
 
 When it registers the end user’s images, iiif.ly assigns metadata to group images together, and to preserve the order.
 
 The iiif.ly customer (API user) has configured a Named Query to return a IIIF manifest.
 
-Template: `https://dlcs.io/resource/{customer}/{query-name}/{space-name}/{string1}`
+Template for consuming NamedQuery: `https://dlcs.io/iiif-resource/{customer}/{query-name}/{space-name}/{string1}`
+
+NamedQuery as saved in database: `manifest=s1&sequence=n1&canvas=n2&spacename=p1&s1=p2`
 
 The **Named Query** – in response to requests that match this template,
+
 1. Select all the images in {space-name} with a string1 value of {string1} and order them by {number1}
 2. Project the images into a manifest with one sequence where each canvas in the sequence corresponds to one image
 
-Example: 
+## Explanation
+
+The following keywords can be used when creating a named query:
+
+| Property Name | Description                                                                                  | Example         |
+|---------------|----------------------------------------------------------------------------------------------|-----------------|
+| space         | Matches a space by Id (by default named queries will search all images for customer)         | `&space=p1`     |
+| spacename     | Matches a space by name (by default named queries will search all images for customer)       | `&spacename=p1` |
+| manifest      | How to group images                                                                          | `&manifest=s1`  |
+| sequence      | How to filter images in manifest                                                             | `&sequence=n1`  |
+| canvas        | Ordering to apply to each image on canvas                                                    | `&canvas=n2`    |
+| s1            | String1 metadata field                                                                       | `&manifest=s1`  |
+| s2            | String2 metadata field                                                                       | `&s1=p1`        |
+| s3            | String3 metadata field                                                                       | `&manifest=s3`  |
+| n1            | Number 1 metadata field                                                                      | `&sequence=n1`  |
+| n2            | Number 2 metadata field                                                                      | `&canvas=n2`    |
+| n3            | Number 3 metadata field                                                                      | `&n1=p2`        |
+| p*            | Identifies url parameters.Anything after `iiif-resource/{customer}/{query-name}` (`/1/2/3`) | `&n1=p2`        |
+| #*            | When used in template adds the value to end of URL, effectively hardcoding a parameter       | `&manifest=s1`  |
+
+## Example URLs: 
 
 [https://dlcs.io/resource/4/iiifly/28EC11C6/a5425f9b](https://dlcs.io/resource/4/iiifly/28EC11C6/a5425f9b)