Update docs with any differences to impl

dlcs · May 14, 2020 · 5c53fb0 · 5c53fb0
1 parent 61491ca
commit 5c53fb0
Show file tree

Hide file tree

Showing 14 changed files with 120 additions and 98 deletions.
diff --git a/API_Reference/authservice.md b/API_Reference/authservice.md
@@ -11,13 +11,16 @@
 ## Supported operations
 
 
-| Method | Label                                          | Expects           | Returns           | Statuses                                                              |
-|--------|------------------------------------------------|-------------------|-------------------|-----------------------------------------------------------------------|
-| GET    | Retrieve a Auth Service                        |                   | vocab:AuthService | 200 OK, 404 Not found                                                 |
-| PUT    | create or replace a Auth Service               | vocab:AuthService | vocab:AuthService | 200 OK, 201 Created Auth Service, 404 Not found                       |
-| PATCH  | Update the supplied fields of the Auth Service | vocab:AuthService | vocab:AuthService | 205 Accepted Auth Service, reset view, 400 Bad request, 404 Not found |
-| DELETE | Delete the Auth Service                        |                   | owl:Nothing       | 205 Accepted Auth Service, reset view, 404 Not found                  |
+| Method | Label                             | Expects           | Returns           | Statuses                                        |
+|--------|-----------------------------------|-------------------|-------------------|-------------------------------------------------|
+| GET    | Retrieve an Auth Service          |                   | vocab:AuthService | 200 OK, 404 Not found                           |
+| PUT    | Create or replace an Auth Service | vocab:AuthService | vocab:AuthService | 200 OK, 201 Created Auth Service, 404 Not found |
+| DELETE | Delete the Auth Service           |                   | owl:Nothing       | 200 OK, 404 Not found                           |
 
+<!--
+PATCH not implemented
+DELETE returns 200, not 205. Not owl:nothing but {"success": true} 
+-->
 
 ## Supported properties
 
@@ -106,6 +109,8 @@ How long a cookie session and bearer token are valid for (seconds)
 
 Child auth services of a parent (relationship between login and token,logout)
 
+<!-- This was /nestedServices Tom to expand with how this is implemented in the DLCS. -->
+
 
 | domain            | range            | readonly | writeonly |
 |-------------------|------------------|----------|-----------|
@@ -137,4 +142,3 @@ External service that can be used by the DLCS to acquire roles for user sessions
 | Method | Label                    | Expects | Returns    | Statuses              |
 |--------|--------------------------|---------|------------|-----------------------|
 | GET    | Retrieve a Role Provider |         | vocab:Role | 200 OK, 404 Not found |
-
diff --git a/API_Reference/batch.md b/API_Reference/batch.md
@@ -125,6 +125,7 @@ Collection of images that have completed processing
 | vocab:Batch | hydra:Collection | True     | False     |
 
 
+<!-- call fails -->
 `/customers/{customer}/queue/batches/{batchId}/completedImages`
 
 
@@ -143,6 +144,7 @@ Collection of images that encountered errors
 | vocab:Batch | hydra:Collection | True     | False     |
 
 
+<!-- call fails -->
 `/customers/{customer}/queue/batches/{batchId}/errorImages`
 
 

diff --git a/API_Reference/customer.md b/API_Reference/customer.md
@@ -14,17 +14,18 @@ A customer represents you, the API user. You only have access to one customer, s
 ## Supported operations
 
 
-| Method | Label               | Expects | Returns        | Statuses              |
-|--------|---------------------|---------|----------------|-----------------------|
-| GET    | Retrieve a Customer |         | vocab:Customer | 200 OK, 404 Not found |
+| Method  | Label               | Expects        | Returns        | Statuses                              |
+|---------|---------------------|----------------|----------------|---------------------------------------|
+| GET     | Retrieve a Customer |                | vocab:Customer | 200 OK, 404 Not found                 |
+| POST[1] | Create a Customer   | vocab:Customer | vocab:Customer | 201 Customer Created, 400 Bad Request |
 
 
 ## Supported properties
 
 
 ### name
 
-The URL-friendly name of the customer, can be used in URLs rather than customerId
+The URL-friendly name of the customer, can be used in URLs rather than customerId.
 
 
 | domain         | range      | readonly | writeonly |
@@ -42,6 +43,16 @@ The display name of the customer
 | vocab:Customer | xsd:string | False    | False     |
 
 
+### acceptedAgreement 
+
+Has the customer accepted the EULA?
+
+
+| domain         | range       | readonly | writeonly |
+|----------------|-------------|----------|-----------|
+| vocab:Customer | xsd:boolean | True     | False     |
+
+
 ### portalUsers (🔗)
 
 Collection of user accounts that can log into the portal. Use this to grant access to others in your organisation
@@ -93,10 +104,10 @@ Collection of configuration settings for retrieving your registered images from
 `/customers/{customer}/originStrategies`
 
 
-| Method | Label                         | Expects              | Returns              | Statuses                                      |
-|--------|-------------------------------|----------------------|----------------------|-----------------------------------------------|
-| GET    | Retrieves all Origin Strategy |                      | hydra:Collection     | 200 OK                                        |
-| POST   | Creates a new Origin Strategy | vocab:OriginStrategy | vocab:OriginStrategy | 201 Origin Strategy created., 400 Bad Request |
+| Method | Label                         | Expects              | Returns              | Statuses                                     |
+|--------|-------------------------------|----------------------|----------------------|----------------------------------------------|
+| GET    | Retrieves all Origin Strategy |                      | hydra:Collection     | 200 OK                                       |
+| POST   | Creates a new Origin Strategy | vocab:OriginStrategy | vocab:OriginStrategy | 201 Origin Strategy created, 400 Bad Request |
 
 
 ### authServices (🔗)
@@ -228,12 +239,4 @@ Storage policy for the Customer. See the [StoragePolicy](storagepolicy.md) topic
 | GET    | Returns the customer storage resource |         | vocab:CustomerStorage | 200 OK   |
 
 
-### acceptedAgreement 
-
-Has the customer accepted the EULA?
-
-
-| domain         | range       | readonly | writeonly |
-|----------------|-------------|----------|-----------|
-| vocab:Customer | xsd:boolean | True     | False     |
-
+[1] - requires Admin credentials. POST to `/customers/`
diff --git a/API_Reference/customerstorage.md b/API_Reference/customerstorage.md
@@ -14,9 +14,9 @@ Information resource that shows the current storage use for a Customer or for an
 ## Supported operations
 
 
-| Method | Label                      | Expects | Returns               | Statuses              |
-|--------|----------------------------|---------|-----------------------|-----------------------|
-| GET    | Retrieve a CustomerStorage |         | vocab:CustomerStorage | 200 OK, 404 Not found |
+| Method | Label                    | Expects | Returns               | Statuses              |
+|--------|--------------------------|---------|-----------------------|-----------------------|
+| GET    | Retrieve CustomerStorage |         | vocab:CustomerStorage | 200 OK, 404 Not found |
 
 
 ## Supported properties

diff --git a/API_Reference/image.md b/API_Reference/image.md
@@ -14,13 +14,17 @@ The "Image" resource is the DLCS view of an asset that you have registered (Imag
 ## Supported operations
 
 
-| Method | Label                                   | Expects     | Returns     | Statuses                                                       |
-|--------|-----------------------------------------|-------------|-------------|----------------------------------------------------------------|
-| GET    | Retrieve a Image                        |             | vocab:Image | 200 OK, 404 Not found                                          |
-| PUT    | create or replace a Image               | vocab:Image | vocab:Image | 200 OK, 201 Created Image, 404 Not found                       |
-| PATCH  | Update the supplied fields of the Image | vocab:Image | vocab:Image | 205 Accepted Image, reset view, 400 Bad request, 404 Not found |
-| DELETE | Delete the Image                        |             | owl:Nothing | 205 Accepted Image, reset view, 404 Not found                  |
-
+| Method | Label                                   | Expects     | Returns     | Statuses                                 |
+|--------|-----------------------------------------|-------------|-------------|------------------------------------------|
+| GET    | Retrieve a Image                        |             | vocab:Image | 200 OK, 404 Not found                    |
+| PUT    | create or replace a Image               | vocab:Image | vocab:Image | 200 OK, 201 Created Image, 404 Not found |
+| PATCH  | Update the supplied fields of the Image | vocab:Image | vocab:Image | 200 OK, 400 Bad request, 404 Not found   |
+| DELETE | Delete the Image                        |             | owl:Nothing | 200 OK, 404 Not found                    |
+
+<!--
+PATCH returns 200, not 205
+DELETE returns 200, not 205. Not owl:nothing but {"success": true} 
+-->
 
 ## Supported properties
 
@@ -49,6 +53,8 @@ Origin endpoint from where the original image can be acquired (or was acquired)
 
 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? -->
+
 
 | domain      | range      | readonly | writeonly |
 |-------------|------------|----------|-----------|
@@ -215,6 +221,11 @@ 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/introduction.md b/API_Reference/introduction.md
@@ -37,9 +37,7 @@ Each type-specific context defines the vocabulary for that type, for example:
 }
 ```
 
-The full description of the types and their supported properties and operations is available at the "vocab" URI:
-
-`https://dlcs.azurewebsites.net/vocab`
+The full description of the types and their supported properties and operations is available at the "vocab" URI `https://dlcs.azurewebsites.net/vocab`, or at the root of the API.
 
 A diagram showing the full model is [available here](resource_model.md); the rest of this section looks at each resource type in detail.
 

diff --git a/API_Reference/key.md b/API_Reference/key.md
@@ -16,10 +16,15 @@ To obtain a key and a secret, make an empty POST to this collection with adminis
 ## Supported operations
 
 
-| Method | Label                                                                                | Expects     | Returns   | Statuses                                             |
-|--------|--------------------------------------------------------------------------------------|-------------|-----------|------------------------------------------------------|
-| GET    | Returns keys allocated to this customer resource                                     |             | vocab:Key |                                                      |
-| POST   | Submit an empty POST and the DLCS will generate a key and secret. Requires eleveated | owl:Nothing | vocab:Key | 201 Job has been accepted - key created and returned |
+| Method | Label                                                                               | Expects     | Returns   | Statuses                     |
+|--------|-------------------------------------------------------------------------------------|-------------|-----------|------------------------------|
+| GET    | Returns keys allocated to this customer resource                                    |             | vocab:Key |                              |
+| POST   | Submit an empty POST and the DLCS will generate a key and secret. Requires elevated | owl:Nothing | vocab:Key | 201 Key created and returned |
+
+<!-- 
+empty POST is returning 500 
+GET for specific key /customers/{customer}/keys/{keyId} 500
+-->
 
 
 ## Supported properties

diff --git a/API_Reference/namedquery.md b/API_Reference/namedquery.md
@@ -13,6 +13,11 @@ 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.
 
 
+<!-- 
+this returns a 500
+need to expand general docs on this
+ -->
+
 `/customers/{customer}/namedQueries/{named-query}`
 
 

diff --git a/API_Reference/originstrategy.md b/API_Reference/originstrategy.md
@@ -59,20 +59,34 @@ Whether the DLCS needs stored credentials to fetch images with this strategy
 
 As a customer you can provide information to the DLCS to allow it to fetch your images from their origin endpoints. Every customer has a default origin strategy, which is for the DLCS to attempt to fetch the image from its origin URL without presenting credentials. This is fine for images that are publicly available, but is unlikely to be appropriate for images you are exposing from your asset management system. You might have a service that is available only to the DLCS, or an FTP site. The DLCS has a predefined set of mechanisms for obtaining resources over HTTP, FTP, S3 etc. In your customer origin strategies you match these predefined strategies to regexes that match your origin URLs and credentials that the DLCS can use when requesting your assets.
 
+`/customers/{customer}/originStrategies/`
+
+
+### Supported operations
+
+
+| Method | Label                          | Expects                      | Returns                      | Statuses                    |
+|--------|--------------------------------|------------------------------|------------------------------|-----------------------------|
+| GET    | Retrieve all Origin Strategies |                              | vocab:CustomerOriginStrategy | 200 OK                      |
+| POST   | create an Origin Strategy      | vocab:CustomerOriginStrategy | vocab:CustomerOriginStrategy | 201 Created Origin Strategy |
+
 
 `/customers/{customer}/originStrategies/{originStrategy}`
 
 
 ### Supported operations
 
 
-| Method | Label                                             | Expects                      | Returns                      | Statuses                                                                 |
-|--------|---------------------------------------------------|------------------------------|------------------------------|--------------------------------------------------------------------------|
-| GET    | Retrieve a Origin Strategy                        |                              | vocab:CustomerOriginStrategy | 200 OK, 404 Not found                                                    |
-| PUT    | create or replace a Origin Strategy               | vocab:CustomerOriginStrategy | vocab:CustomerOriginStrategy | 200 OK, 201 Created Origin Strategy, 404 Not found                       |
-| PATCH  | Update the supplied fields of the Origin Strategy | vocab:CustomerOriginStrategy | vocab:CustomerOriginStrategy | 205 Accepted Origin Strategy, reset view, 400 Bad request, 404 Not found |
-| DELETE | Delete the Origin Strategy                        |                              | owl:Nothing                  | 205 Accepted Origin Strategy, reset view, 404 Not found                  |
+| Method | Label                       | Expects                      | Returns                      | Statuses              |
+|--------|-----------------------------|------------------------------|------------------------------|-----------------------|
+| GET    | Retrieve an Origin Strategy |                              | vocab:CustomerOriginStrategy | 200 OK, 404 Not found |
+| PUT    | Replace an Origin Strategy  | vocab:CustomerOriginStrategy | vocab:CustomerOriginStrategy | 200 OK, 404 Not found |
+| DELETE | Delete the Origin Strategy  |                              | owl:Nothing                  | 200 OK, 404 Not found |
 
+<!--
+PATCH not supported
+DELETE returns 200, not 205. Not owl:nothing but {"success": true}
+-->
 
 ### Supported properties
 

diff --git a/API_Reference/portalrole.md b/API_Reference/portalrole.md
diff --git a/API_Reference/portalrole.png b/API_Reference/portalrole.png