Skip to content

Commit

Permalink
Update api_reference docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@donaldgray
donaldgray committed May 13, 2020
1 parent 3b4c025 commit 61491ca
Show file tree
Hide file tree
Showing 21 changed files with 241 additions and 368 deletions.
20 changes: 7 additions & 13 deletions API_Reference/authservice.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,10 @@

![](authservice.png)

IIIF Authentication Service configuration. The services configured here are exposed by the DLCS on IIIF Image API endpoints, so that a viewer that supports the IIIF Auth specification can interact with them to acquire a cookie that will gain access to the images. The DLCS enforces access control on a customer's behalf (this is essential for performance when many hundreds of image tiles are requested). This means it is the DLCS that implements the IIIF auth flow on your behalf. In one special case, 'clickthrough', you can configure an auth service in the DLCS that needs no runtime interation with your own systems. However, for more complex scenarios, the DLCS will need to direct the user to your (customer) servers during the auth flow, so that they can authenticate against your system. The DLCS then needs to query your system to acquire that user's roles,and thereby determine what level of service it can offer the user for a given protected image. See RoleProvider for imformation. The fields of AuthService give you control over how the service will be presented in a viewer that implements the IIF auth flow.
[IIIF Authentication](https://iiif.io/api/auth/1.0/) Service configuration. The services configured here are exposed by the DLCS on IIIF Image API endpoints, so that a viewer that supports the IIIF Auth specification can interact with them to acquire a cookie that will gain access to the images. The DLCS enforces access control on a customer's behalf (this is essential for performance when many hundreds of image tiles are requested). This means it is the DLCS that implements the IIIF auth flow on your behalf. In one special case, ['clickthrough'](https://iiif.io/api/auth/1.0/#clickthrough-interaction-pattern), you can configure an auth service in the DLCS that needs no runtime interation with your own systems. However, for more complex scenarios, the DLCS will need to direct the user to your (customer) servers during the auth flow, so that they can authenticate against your system. The DLCS then needs to query your system to acquire that user's roles, and thereby determine what level of service it can offer the user for a given protected image. See [RoleProvider](roleprovider.md) for information. The fields of AuthService give you control over how the service will be presented in a viewer that implements the IIF auth flow.


```
/customers/{0}/authServices/{1}
```
`/customers/{customer}/authServices/{authServiceId}`


## Supported operations
Expand Down Expand Up @@ -76,7 +74,7 @@ Label that appears on pages generated by DLCS. If the user needs to see an inter

### pageDescription

Description that appears on pages generated by DLCS. As with the label above, used by the DLCS to generate pagesto present to a user during the flow.
Description that appears on pages generated by DLCS. As with the label above, used by the DLCS to generate pages to present to a user during the flow.


| domain | range | readonly | writeonly |
Expand Down Expand Up @@ -104,7 +102,7 @@ How long a cookie session and bearer token are valid for (seconds)
| vocab:AuthService | xsd:nonNegativeInteger | False | False |


### nestedServices (🔗)
### childAuthService (🔗)

Child auth services of a parent (relationship between login and token,logout)

Expand All @@ -114,9 +112,7 @@ Child auth services of a parent (relationship between login and token,logout)
| vocab:AuthService | hydra:Collection | True | False |


```
/customers/{0}/authServices/{1}/nestedServices
```
`/customers/{customer}/authServices/{childAuthServiceId}`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -127,17 +123,15 @@ Child auth services of a parent (relationship between login and token,logout)

### roleProvider (🔗)

External service that can be used by the DLCS to acquire roles for user sessions. See RoleProvider.
External service that can be used by the DLCS to acquire roles for user sessions. See [RoleProvider](roleprovider.md).


| domain | range | readonly | writeonly |
|-------------------|--------------------|----------|-----------|
| vocab:AuthService | vocab:RoleProvider | True | False |


```
/customers/{0}/authServices/{1}/roleProvider
```
`/customers/{customer}/authServices/{authServiceId}/roleProvider`


| Method | Label | Expects | Returns | Statuses |
Expand Down
30 changes: 14 additions & 16 deletions API_Reference/batch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,17 @@

Represents a submitted job of images. Typically you'd interact with this while it is being processed, or to update your internal systems with the status of images on the DLCS. The DLCS might clear out old batches after a specific time interval.

`/customers/{customer}/queue/batches`

## Supported operations


| Method | Label | Expects | Returns | Statuses |
|--------|----------------------|---------|-------------|-----------------------|
| GET | Retrieve all Batches | | vocab:Batch | 200 OK, 404 Not found |

```
/customers/{0}/queue/batches/{1}
```

`/customers/{customer}/queue/batches/{batchId}`

## Supported operations

Expand Down Expand Up @@ -73,7 +79,7 @@ Total number of error images in the batch

### superseded

Has this batch been superseded by another? An image can only be associated with one active batch at a time. If no images are associated with this batch, then it has been superseded by one or more later batches. The DLCS does notupdate this property automatically, you can force an update by POSTing to the /test resource of a batch.
Has this batch been superseded by another? An image can only be associated with one active batch at a time. If no images are associated with this batch, then it has been superseded by one or more later batches. The DLCS does not update this property automatically, you can force an update by POSTing to the /test resource of a batch.


| domain | range | readonly | writeonly |
Expand Down Expand Up @@ -101,9 +107,7 @@ Collection of all the images in the batch
| vocab:Batch | hydra:Collection | True | False |


```
/customers/{0}/queue/batches/{1}/images
```
`/customers/{customer}/queue/batches/{batchId}/images`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -121,9 +125,7 @@ Collection of images that have completed processing
| vocab:Batch | hydra:Collection | True | False |


```
/customers/{0}/queue/batches/{1}/completedImages
```
`/customers/{customer}/queue/batches/{batchId}/completedImages`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -141,9 +143,7 @@ Collection of images that encountered errors
| vocab:Batch | hydra:Collection | True | False |


```
/customers/{0}/queue/batches/{1}/errorImages
```
`/customers/{customer}/queue/batches/{batchId}/errorImages`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -161,7 +161,5 @@ POST to this to force an update of the batch's superseded property. Returns JSON
| vocab:Batch | hydra:Collection | True | False |


```
/customers/{0}/queue/batches/{1}/test
```
`/customers/{customer}/queue/batches/{batchId}/test`

103 changes: 58 additions & 45 deletions API_Reference/customer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,14 @@

![](customer.png)

A customer represents you, the API user. You only have access to one customer, so it is your effective entry point for the API. The only interation you can have with your Customer resource directly is updating the display name, but it provides links (🔗) tocollections of all the other resources.
A customer represents you, the API user. You only have access to one customer, so it is your effective entry point for the API. The only interation you can have with your Customer resource directly is updating the display name, but it provides links (🔗) to collections of all the other resources.


```
/customers/{0}
```
`/customers/{customer}`

## Example

http://dlcs.azurewebsites.net/customers/4
[https://dlcs.azurewebsites.net/customers/4](https://dlcs.azurewebsites.net/customers/4)

## Supported operations

Expand All @@ -26,7 +24,7 @@ http://dlcs.azurewebsites.net/customers/4

### name

The URL-friendly name of the customer
The URL-friendly name of the customer, can be used in URLs rather than customerId


| domain | range | readonly | writeonly |
Expand Down Expand Up @@ -54,9 +52,7 @@ Collection of user accounts that can log into the portal. Use this to grant acce
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/portalUsers
```
`/customers/{customer}/portalUsers`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -67,17 +63,15 @@ Collection of user accounts that can log into the portal. Use this to grant acce

### namedQueries (🔗)

Collection of all the Named Queries you have configured (plus those provided 'out of the box'). See the NamedQuery topic for further information
Collection of all the Named Queries you have configured (plus those provided 'out of the box'). See the [NamedQuery](namedquery.md) topic for further information


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/namedQueries
```
`/customers/{customer}/namedQueries`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -88,17 +82,15 @@ Collection of all the Named Queries you have configured (plus those provided 'ou

### originStrategies (🔗)

Collection of configuration settings for retrieving your registered images from their origin URLs. If your images come from multiple locations you will have multiple origin strategies. See the OriginStrategy topic.
Collection of configuration settings for retrieving your registered images from their origin URLs. If your images come from multiple locations you will have multiple origin strategies. See the [OriginStrategy](originstrategy.md) topic for futher information


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/originStrategies
```
`/customers/{customer}/originStrategies`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -109,17 +101,15 @@ Collection of configuration settings for retrieving your registered images from

### authServices (🔗)

Collection of IIIF Authentication services available for use with your images. The images are associated with the auth services via Roles. An AuthService is a means of acquirung a role.
Collection of IIIF Authentication services available for use with your images. The images are associated with the auth services via Roles. An [AuthService](authservice.md) is a means of acquiring a role.


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/authServices
```
`/customers/{customer}/authServices`


| Method | Label | Expects | Returns | Statuses |
Expand All @@ -128,25 +118,41 @@ Collection of IIIF Authentication services available for use with your images. T
| POST | Creates a new Auth Service | vocab:AuthService | vocab:AuthService | 201 Auth Service created., 400 Bad Request |


### roleProviders (🔗)

Collection of the available role providers. In order for a user to see an image, the user must have at least one role associated with the image. [RoleProviders](roleprovider.md) represent how DLCS acquires roles.


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


`/customers/{customer}/roleProviders`


| Method | Label | Expects | Returns | Statuses |
|--------|-----------------------------|---------|------------------|----------|
| GET | Retrieves all RoleProviders | | hydra:Collection | 200 OK |


### roles (🔗)

Collection of the available roles you can assign to your images. In order for a user to see an image, the user must have the role associated with the image, or one of them. Users interact with an AuthService to acquire a role or roles.
Collection of the available roles you can assign to your images. In order for a user to see an image, the user must have the role associated with the image, or one of them. Users interact with an [AuthService](authservice.md) to acquire a role or roles.


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/roles
```
`/customers/{customer}/roles`


| Method | Label | Expects | Returns | Statuses |
|--------|---------------------|-------------|------------------|-------------------------------------|
| GET | Retrieves all Space | | hydra:Collection | 200 OK |
| POST | Creates a new Space | vocab:Space | vocab:Space | 201 Space created., 400 Bad Request |
| Method | Label | Expects | Returns | Statuses |
|--------|---------------------|------------|------------------|-----------------------------------|
| GET | Retrieves all Roles | | hydra:Collection | 200 OK |
| POST | Creates a new Role | vocab:Role | vocab:Role | 201 Role created, 400 Bad Request |


### queue (🔗)
Expand All @@ -159,60 +165,67 @@ The Customer's view on the DLCS ingest queue. As well as allowing you to query t
| vocab:Customer | vocab:Queue | True | False |


```
/customers/{0}/queue
```
`/customers/{customer}/queue`


| Method | Label | Expects | Returns | Statuses |
|--------|-----------------------------------------------|------------------|-------------|--------------------------------------------------------|
| GET | Returns the queue resource | | vocab:Queue | |
| GET | Returns the queue resource | | vocab:Queue | 200 OK |
| POST | Submit an array of Image and get a batch back | hydra:Collection | vocab:Batch | 201 Job has been accepted - Batch created and returned |


### spaces (🔗)

Collection of all the Space resources associated with your customer. A space allows you to partition images, have different default roles and tags, etc. See the Space topic.
Collection of all the Space resources associated with your customer. A space allows you to partition images, have different default roles and tags, etc. See the [Space](space.md) topic for more information.


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/spaces
```
`/customers/{customer}/spaces`


| Method | Label | Expects | Returns | Statuses |
|--------|----------------------------|---------|-------------|----------|
| GET | Returns the space resource | | vocab:Space | 200 OK |


### keys (🔗)

Api keys allocated to this customer. The accompanying secret is only available at creation time. To obtain a key and a secret, make an empty POST to this collection with administrator privileges and the returned Key object will include the generates secret.
Api keys allocated to this customer. The accompanying secret is only available at creation time. To obtain a key and a secret, make an empty POST to this collection with administrator privileges and the returned [Key](key.md) object will include the generated secret.


| domain | range | readonly | writeonly |
|----------------|------------------|----------|-----------|
| vocab:Customer | hydra:Collection | True | False |


```
/customers/{0}/keys
```
`/customers/{customer}/keys`


| Method | Label | Expects | Returns | Statuses |
|--------|------------------------------|---------|-----------|----------|
| GET | Returns the api key resource | | vocab:Key | 200 OK |


### storage (🔗)

Storage policy for the Customer
Storage policy for the Customer. See the [StoragePolicy](storagepolicy.md) topic for more information


| domain | range | readonly | writeonly |
|----------------|-----------------------|----------|-----------|
| vocab:Customer | vocab:CustomerStorage | True | False |


```
/customers/{0}/storage
```
`/customers/{customer}/storage`


| Method | Label | Expects | Returns | Statuses |
|--------|---------------------------------------|---------|-----------------------|----------|
| GET | Returns the customer storage resource | | vocab:CustomerStorage | 200 OK |


### acceptedAgreement
Expand Down

0 comments on commit 61491ca

Please sign in to comment.