mirror of
https://gitlab.com/wgp/dougal/software.git
synced 2025-12-06 10:17:07 +00:00
4777 lines
211 KiB
YAML
4777 lines
211 KiB
YAML
openapi: 3.0.0
|
||
info:
|
||
version: 0.4.0
|
||
title: Dougal API
|
||
description: >
|
||
Public API of the Dougal seismic production & data analysis tool.
|
||
|
||
This API may be used by anyone authorised to access a Dougal system. Access via a client other than the official web frontend is supported provided that it is done in line with this document and the use is not abusive or disruptive and doesn't inconvenience other users.
|
||
|
||
## Logging in
|
||
|
||
All endpoints require a valid login for authentication and/or authorisation. Some endpoints may require elevated privileges.
|
||
|
||
Log in may be explicit, by using the appropriate endpoint and presenting valid user credentials, or implicit by making a request from an authorised network or host. In the latter case, a session token will be returned in a `Set-Cookie` response header, along with the relevant response data. Users should expect a `Set-Cookie` header containing a cookie named `JWT` at any point during their interaction with the API and, upon receiving one, they should use the value contained therein as a token to be presented in subsequent requests until a new token is received. No state is kept server-side concerning user sessions.
|
||
|
||
### User roles
|
||
|
||
There are three categories of user supported by the Dougal system in this version of the API, these are called ‘roles’ and are as follows:
|
||
|
||
* `guest` role: has read-only access (`GET` endpoints).
|
||
|
||
* `user` role: has read and write access to endpoints not dealing with administrative data.
|
||
|
||
* `master` role: has read and write access to the same endpoints as the `user` role and to additional endpoints dealing with administrative data, such as the ability to set the system's configuration, define new surveys, etc. Note that currently no endpoints exist requiring `master` access.
|
||
|
||
### Logging out
|
||
|
||
Albeit there is no explicit need to log out given the token-based, stateless authentication and authorisation architecture, a convenience endpoint is provided that will cause a browser to expire the `JWT` authentication cookie.
|
||
|
||
contact:
|
||
name: Dougal support
|
||
email: dougal-support@aaltronav.eu
|
||
url: https://gitlab.com/wgp/dougal/software/-/issues
|
||
servers:
|
||
- url: https://dougal.aaltronav.eu/api
|
||
description: Dougal demo server
|
||
- url: https://248.dougal.aaltronav.eu/api
|
||
description: Crew 248, external access
|
||
- url: https://lan.248.dougal.aaltronav.eu/api
|
||
description: Crew 248, LAN access only
|
||
|
||
tags:
|
||
-
|
||
name: project
|
||
description: Project-related information
|
||
-
|
||
name: preplot
|
||
description: Preplot data
|
||
-
|
||
name: sequences
|
||
description: Raw and final sequence data, and online information
|
||
-
|
||
name: planner
|
||
description: Sequences planned to be shot
|
||
-
|
||
name: log
|
||
description: Project events log
|
||
-
|
||
name: qc
|
||
description: Project quality control definition and results
|
||
-
|
||
name: metadata
|
||
description: Project items metadata
|
||
-
|
||
name: navdata
|
||
description: Data from navigation headers
|
||
-
|
||
name: asaqc
|
||
description: |
|
||
Interface to [Equinor](https://equinor.com/)'s [ASAQC Vessel Track](https://api.equinor.com/docs/services/vessel-track/) application programming interface.
|
||
|
||
Used for transferring line log data from the vessel to the Equinor office. As implemented as of October 2021, for each sequence that is queued for sending it transfers the following files:
|
||
|
||
* SeisJSON file containing sequence event data.
|
||
* PDF file which is a representation of the corresponding SeisJSON.
|
||
-
|
||
name: configuration
|
||
description: Dougal instance configuration endpoints.
|
||
-
|
||
name: users
|
||
description: User management
|
||
-
|
||
name: misc
|
||
description: Miscellaneous endpoints
|
||
|
||
components:
|
||
securitySchemes:
|
||
|
||
# Read-only access
|
||
BearerAuthGuest:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: >
|
||
This authentication is used by users having the `guest` role, giving read-only access to the Dougal system. A token may be obtained by either explicitly logging in with authorised credentials or by making the request from an authorised network or host – in the latter case, a session token will be returned along with the first response in a `Set-Cookie` header.
|
||
|
||
Tokens are valid for a limited amount of time. After this has elapsed, a new token will be generated for network- or host-authorised users. Users with explicitly initiated logins will have to reauthenticate.
|
||
|
||
Users may present the returned token in an `Authorization: Bearer …` header or as a cookie, whichever is most convenient.
|
||
CookieAuthGuest:
|
||
type: apiKey
|
||
in: cookie
|
||
name: JWT
|
||
description: >
|
||
This authentication is used by users having the `guest` role, giving read-only access to the Dougal system. A token may be obtained by either explicitly logging in with authorised credentials or by making the request from an authorised network or host – in the latter case, a session token will be returned along with the first response in a `Set-Cookie` header.
|
||
|
||
Tokens are valid for a limited amount of time. After this has elapsed, a new token will be generated for network- or host-authorised users. Users with explicitly initiated logins will have to reauthenticate.
|
||
|
||
Users may present the returned token in an `Authorization: Bearer …` header or as a cookie, whichever is most convenient.
|
||
|
||
|
||
# Read-write access
|
||
BearerAuthUser:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: >
|
||
This authentication is used by users having the `user` role, giving read and write access to the Dougal system, except for administrative endpoints. See the description of `BearerAuthGuest` for more information on how to obtain a token.
|
||
CookieAuthUser:
|
||
type: apiKey
|
||
in: cookie
|
||
name: JWT
|
||
description: >
|
||
This authentication is used by users having the `user` role, giving read and write access to the Dougal system, except for administrative endpoints. See the description of `CookieAuthGuest` for more information on how to obtain a token.
|
||
|
||
|
||
# Read-write access
|
||
BearerAuthAdmin:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: >
|
||
This authentication is used by users having the `admin` role, giving read and write access to the Dougal system, including administrative endpoints. See the description of `BearerAuthGuest` for more information on how to obtain a token.
|
||
CookieAuthAdmin:
|
||
type: apiKey
|
||
in: cookie
|
||
name: JWT
|
||
description: >
|
||
This authentication is used by users having the `admin` role, giving read and write access to the Dougal system, including administrative endpoints. See the description of `CookieAuthGuest` for more information on how to obtain a token.
|
||
|
||
responses:
|
||
"400":
|
||
description: >
|
||
There was a problem with the syntax or the data of the request. Additional information may be provided in the response body.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
message:
|
||
type: string
|
||
|
||
"401":
|
||
description: Unauthorised. Either no credentials were provided or the user does not have sufficient privileges to perform this operation.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
message:
|
||
type: string
|
||
|
||
"404":
|
||
description: >
|
||
Not found. Also returned when the user does not sufficient access rights to it
|
||
and the server does not wish to reveal the resource's existence.
|
||
|
||
"412":
|
||
description: >
|
||
[Precondition failed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412).
|
||
The [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
|
||
value does not match the current [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
|
||
value of the resource.
|
||
Typically this occurs when the resource has been modified and the request is not using the latest value.
|
||
|
||
"428":
|
||
description: >
|
||
[Precondition Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428).
|
||
This endpoint requires an [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
|
||
and the request did not provide one.
|
||
|
||
|
||
parameters:
|
||
Project:
|
||
description: Alphanumeric identifier for a project.
|
||
name: project
|
||
in: path
|
||
schema:
|
||
type: string
|
||
required: true
|
||
example: eq20211
|
||
|
||
Line:
|
||
description: Preplot line number
|
||
name: line
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 5210
|
||
|
||
Point:
|
||
description: Preplot point number
|
||
name: point
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 2576
|
||
|
||
Sequence:
|
||
description: Sequence number
|
||
name: sequence
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 115
|
||
|
||
Shotpoint:
|
||
description: Shotpoint number
|
||
name: shot
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 2576
|
||
|
||
EventID:
|
||
description: Event ID
|
||
name: id
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 14707
|
||
|
||
Since:
|
||
description: Starting epoch
|
||
name: since
|
||
in: path
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
required: true
|
||
example: 1970-01-01T00:00:00Z
|
||
|
||
QueryLimit:
|
||
description: Maximum number of results to return
|
||
name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
|
||
QueryOffset:
|
||
description: The number of items to skip before starting to collect the result set
|
||
name: offset
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
|
||
QueryProject:
|
||
description: |
|
||
Subset of attributes to be returned.
|
||
|
||
Some endpoints can perform [projections](https://en.wikipedia.org/wiki/Projection_(relational_algebra)) on their result sets. This parameter controls the set of attributes that are to be returned. Its format is a string where each parameter name is separated by any of the following characters: space, comma, colon or semicolon. Attribute names are truncated at the first dot (`.`) if they contain any.
|
||
name: project
|
||
in: query
|
||
schema:
|
||
type: string
|
||
pattern: "(([^\\s,;:]+)(\\s*[,;:\\s]\\s*)?)+"
|
||
example: "line,point,tstamp"
|
||
|
||
QueryMime:
|
||
name: mime
|
||
description: |
|
||
Ask for the representation of the requested resource to be provided in the indicated MIME type. Overrides the [`Accept`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) request header values (if any).
|
||
|
||
Note that the server is not obliged to honour the requested type and a default (usually `application/json`) might be provided instead. Always check the response's [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header.
|
||
in: query
|
||
schema:
|
||
type: string
|
||
|
||
QueryFilename:
|
||
name: filename
|
||
description: |
|
||
Cause the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header to be set and suggest a file name to download as.
|
||
|
||
Note that the [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) response header is not affected by this parameter.
|
||
in: query
|
||
schema:
|
||
type: string
|
||
|
||
CSVDelimiter:
|
||
description: Delimiter value to use in CSV requests or responses.
|
||
name: delimiter
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: ","
|
||
|
||
CSVFields:
|
||
description: Fields to return in CSV responses.
|
||
name: fields
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: timestamp,sequence,point,text
|
||
|
||
CSVHeader:
|
||
description: Whether to return the header row in CSV responses. It defaults to **`true`**. If present, any value other than `true` or `1` represent **`false`**.
|
||
name: header
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: f
|
||
|
||
Unique:
|
||
description: |
|
||
Return unique results. Any value at all represents `true`.
|
||
name: unique
|
||
in: query
|
||
schema:
|
||
type: string
|
||
pattern: ".+"
|
||
example: "t"
|
||
|
||
ETag:
|
||
name: ETag
|
||
in: header
|
||
description: >
|
||
Response [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header.
|
||
Used when modifying a resource to detect conflicting updates.
|
||
schema:
|
||
type: string
|
||
|
||
If-Match:
|
||
name: If-Match
|
||
in: header
|
||
type: string
|
||
description: >
|
||
The [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
|
||
must match the `ETag` value of the corresponding GET request for the resource.
|
||
required: true
|
||
|
||
|
||
schemas:
|
||
Duration:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
hours:
|
||
type: integer
|
||
minutes:
|
||
type: integer
|
||
seconds:
|
||
type: integer
|
||
milliseconds:
|
||
type: number
|
||
|
||
# GeoJSON schemas come from http://schemas.opengis.net/ogcapi/
|
||
GeoJSONPoint:
|
||
$ref: "ogcapi/features/part1/1.0/openapi/schemas/pointGeoJSON.yaml"
|
||
|
||
GeoJSONLinestring:
|
||
$ref: "ogcapi/features/part1/1.0/openapi/schemas/linestringGeoJSON.yaml"
|
||
|
||
GeoJSONFeature:
|
||
$ref: "ogcapi/features/part1/1.0/openapi/schemas/featureGeoJSON.yaml"
|
||
|
||
Label:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The label's name. Uniqueness is not enforced but non-unique label names may cause unexpected results.
|
||
example: Nav
|
||
data:
|
||
description: Label metadata
|
||
type: object
|
||
properties:
|
||
view:
|
||
description: Visual attributes
|
||
type: object
|
||
properties:
|
||
colour:
|
||
type: string
|
||
description: "Label colour. Either an hex colour or a colour name."
|
||
example: "#EF9A9A"
|
||
description:
|
||
type: string
|
||
description: A short textual description for the label. May be shown as a tooltip by user agents.
|
||
example: Navigation events
|
||
model:
|
||
description: The label's data model
|
||
type: object
|
||
properties:
|
||
user:
|
||
type: boolean
|
||
description: "`true` if users can manually apply this label, `false` if this is a system label."
|
||
multiple:
|
||
type: boolean
|
||
description: "`true` if the label can appear multiple times in the same acquisition sequence; if `false`, any new instance of the label when applied to an acquisition sequence will cause the old instance to be removed."
|
||
|
||
PresetRemark:
|
||
description: |
|
||
A canonical way to describe an event.
|
||
|
||
The aim of preset remarks is to reduce ambiguity and assist users who may not be fully conversant
|
||
with the language being used.
|
||
type: object
|
||
properties:
|
||
text:
|
||
type: string
|
||
description: |
|
||
If this instance has no child items, this is the textual content of the remark.
|
||
|
||
If there are child items, this is a description of the child items. Preset remark
|
||
lists are intended to be presented in user interfaces as a multi-level menu or
|
||
similar element.
|
||
labels:
|
||
description: |
|
||
Labels associated with this remark or with its child items.
|
||
If the text matches a predefined label name, that will be used, else a default label
|
||
will be created.
|
||
type: array
|
||
items:
|
||
type: string
|
||
items:
|
||
description: For convenience and accessibility, remarks may be grouped hierarchically.
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PresetRemark"
|
||
|
||
PresetRemarksList:
|
||
description: A list of preset remarks.
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PresetRemark"
|
||
|
||
PresetRemarksSet:
|
||
description: |
|
||
Preset remarks may be grouped into *sets*, and these sets imported into individual projects,
|
||
or different sets may be presented to different users depending on their role, etc.
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PresetRemark"
|
||
|
||
|
||
AbstractDelimitedStringDecoderFieldDefinition:
|
||
# Only the required properties of the field definition object
|
||
type: object
|
||
required: [ column ]
|
||
properties:
|
||
column:
|
||
description: Zero-based field index
|
||
type: number
|
||
minimum: 0
|
||
|
||
|
||
DelimitedStringDecoderFieldDefinition:
|
||
allOf:
|
||
- $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
|
||
-
|
||
type: object
|
||
description: Arbitrary properties
|
||
required: [ offset, length ]
|
||
properties:
|
||
type:
|
||
description: |
|
||
Type of field. An attempt will be made to convert the value from a text string to one the following:
|
||
|
||
Value | Type
|
||
--------|-----
|
||
`int` | An integer
|
||
`float` | A floating point number
|
||
`bool` | A boolean (**true** or **false**)
|
||
`str` | A text string
|
||
type: string
|
||
default: str
|
||
enum:
|
||
- int
|
||
- float
|
||
- bool
|
||
- str
|
||
enum:
|
||
description: |
|
||
Match the field against a list of predefined values and transform the output if one matches.
|
||
type: array
|
||
items:
|
||
-
|
||
description: A key / value dictionary.
|
||
type: object
|
||
patternProperties:
|
||
"^.+$":
|
||
description: Replacement value if the key matches.
|
||
type: string
|
||
default:
|
||
description: If this field cannot be decoded or none of the `enum` values match, assign this value to the field.
|
||
type: [ int, float, bool, str ]
|
||
|
||
|
||
DelimitedStringDecoderDelimiterDefinition:
|
||
type: string
|
||
minLength: 1
|
||
description: Delimiter character or sequence of characters.
|
||
|
||
|
||
DelimitedStringDecoderDefinition:
|
||
type: object
|
||
required: [ fields ]
|
||
properties:
|
||
example:
|
||
type: string
|
||
description: A specimen piece of text that can be used to illustrate a typical form of the string to be decoded. The decoder is line-based but the example string can consist of multiple lines.
|
||
delimiter:
|
||
$ref: "#/components/schemas/DelimitedStringDecoderDelimiterDefinition"
|
||
fields:
|
||
type: object
|
||
description: A dictionary of property names and their definitions.
|
||
patternProperties:
|
||
"^.+$":
|
||
$ref: "#/components/schemas/DelimitedStringDecoderFieldDefinition"
|
||
|
||
|
||
AbstractFixedStringDecoderFieldDefinition:
|
||
# Only the required properties of the field definition object
|
||
type: object
|
||
required: [ offset, length ]
|
||
properties:
|
||
offset:
|
||
description: Offset in code points from the beginning of the line
|
||
type: number
|
||
minimum: 0
|
||
length:
|
||
description: Length of this field in code points
|
||
type: number
|
||
minimum: 1
|
||
|
||
|
||
FixedStringDecoderFieldDefinition:
|
||
allOf:
|
||
- $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
|
||
-
|
||
type: object
|
||
description: Arbitrary properties
|
||
required: [ offset, length ]
|
||
properties:
|
||
type:
|
||
description: |
|
||
Type of field. An attempt will be made to convert the value from a text string to one the following:
|
||
|
||
Value | Type
|
||
--------|-----
|
||
`int` | An integer
|
||
`float` | A floating point number
|
||
`bool` | A boolean (**true** or **false**)
|
||
`str` | A text string
|
||
type: string
|
||
default: str
|
||
enum:
|
||
- int
|
||
- float
|
||
- bool
|
||
- str
|
||
enum:
|
||
description: |
|
||
Match the field against a list of predefined values and transform the output if one matches.
|
||
type: array
|
||
items:
|
||
-
|
||
description: A key / value dictionary.
|
||
type: object
|
||
patternProperties:
|
||
"^.+$":
|
||
description: Replacement value if the key matches.
|
||
type: string
|
||
default:
|
||
description: If this field cannot be decoded or none of the `enum` values match, assign this value to the field.
|
||
type: [ int, float, bool, str ]
|
||
|
||
|
||
FixedStringDecoderDefinition:
|
||
type: object
|
||
required: [ fields ]
|
||
properties:
|
||
example:
|
||
type: string
|
||
description: A specimen piece of text that can be used to illustrate a typical form of the string to be decoded. The decoder is line-based but the example string can consist of multiple lines.
|
||
fields:
|
||
type: object
|
||
description: A dictionary of property names and their definitions.
|
||
patternProperties:
|
||
"^.+$":
|
||
$ref: "#/components/schemas/FixedStringDecoderFieldDefinition"
|
||
|
||
|
||
LineNameInfoDefinition:
|
||
allOf:
|
||
- $ref: "#/components/schemas/FixedStringDecoderDefinition"
|
||
- description: |
|
||
Line or file name pattern.
|
||
|
||
Describes how a line or file name is to be decoded.
|
||
- properties:
|
||
fields:
|
||
required: [ sequence ]
|
||
example:
|
||
example: EQ22200-2213130-007.000.P111
|
||
fields:
|
||
line:
|
||
length: 4
|
||
type: int
|
||
offset: 10
|
||
sequence:
|
||
length: 3
|
||
type: int
|
||
offset: 16
|
||
incr:
|
||
enum:
|
||
"1": true
|
||
"2": false
|
||
length: 1
|
||
type: bool
|
||
offset: 8
|
||
attempt:
|
||
length: 1
|
||
type: int
|
||
offset: 14
|
||
file_no:
|
||
length: 3
|
||
type: int
|
||
offset: 20
|
||
year:
|
||
offset: 2
|
||
length: 2
|
||
type: int
|
||
survey_type:
|
||
enum:
|
||
"0": Marine
|
||
"2": OBS/PRM
|
||
offset: 4
|
||
length: 1
|
||
default: Unknown
|
||
type: str
|
||
project_number:
|
||
offset: 5
|
||
length: 2
|
||
type: int
|
||
num_sources:
|
||
enum:
|
||
"0": "2"
|
||
"1": "1"
|
||
"2": "3"
|
||
offset: 9
|
||
length: 1
|
||
type: int
|
||
direction:
|
||
enum:
|
||
"1": 62.10°
|
||
"2": 242.10°
|
||
"3": Orthogonal
|
||
offset: 8
|
||
length: 1
|
||
|
||
|
||
RegExpPatternDefinition:
|
||
type: object
|
||
properties:
|
||
regex:
|
||
type: string
|
||
description: A [JavaScript regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions), potentially containing [capture groups](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences).
|
||
flags:
|
||
type: string
|
||
description: Optional [flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags) applying to the regular expression.
|
||
captures:
|
||
description: |
|
||
Array of capture group names.
|
||
|
||
Each capture group in `regex` should have a corresponding entry in this array,
|
||
regardless of whether the group is actually used or not. For unused groups, a
|
||
non-unique name such as `(ignore)` is acceptable.
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: Capture group name.
|
||
|
||
DataFilePathSpecification:
|
||
type: object
|
||
properties:
|
||
paths:
|
||
description: List of paths in which to search for matching files.
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: Literal path name (globs not allowed here)
|
||
globs:
|
||
description: |
|
||
File name globs.
|
||
|
||
Only files matching at least one of these globs inside one of the paths in `paths`
|
||
will be taken into account.
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: "[Glob](https://tldp.org/LDP/abs/html/globbingref.html) pattern."
|
||
lineNameInfo:
|
||
$ref: "#/components/schemas/LineNameInfoDefinition"
|
||
pattern:
|
||
allOf:
|
||
- deprecated: true
|
||
- $ref: "#/components/schemas/RegExpPatternDefinition"
|
||
- description: |
|
||
File name pattern.
|
||
|
||
Files that pass the glob test must also match this regular expression pattern.
|
||
The regular expression may contain capture groups that will be used to extract
|
||
information from the file name. The pattern is applied to the base file name,
|
||
not to the full path.
|
||
|
||
BinningGridDefinition:
|
||
type: object
|
||
description: Binning grid definition.
|
||
properties:
|
||
theta:
|
||
type: number
|
||
description: Direction of the I axis in degrees.
|
||
I_inc:
|
||
type: number
|
||
description: I-axis increment.
|
||
J_inc:
|
||
type: number
|
||
description: J-axis increment.
|
||
I_width:
|
||
type: number
|
||
description: I-axis bin width. Dougal always assumes the I-axis to be the inline axis.
|
||
J_width:
|
||
type: number
|
||
description: J-axis bin width.
|
||
origin:
|
||
type: object
|
||
description: Bin grid origin
|
||
properties:
|
||
easting:
|
||
type: number
|
||
description: Origin Easting.
|
||
northing:
|
||
type: number
|
||
description: Origin Northing.
|
||
I:
|
||
type: number
|
||
description: I-axis value at origin.
|
||
J:
|
||
type: number
|
||
description: J-axis value at origin.
|
||
|
||
|
||
PreplotFileSpecification:
|
||
type: object
|
||
description: Preplot file specification.
|
||
required: [ path, class, type ]
|
||
properties:
|
||
path:
|
||
type: string
|
||
description: File system path to the file, from the point of view of the host Dougal server. The path must be a child of one of the paths listed in Dougal's global configuration under [`import.mounts`](https://gitlab.com/wgp/dougal/software/-/commit/811864123197099cc13375a914b6cf0fdaef6b22).
|
||
class:
|
||
type: string
|
||
description: |
|
||
Preplot class:
|
||
|
||
- Source points (`S`)
|
||
- Vessel points (`V`)
|
||
type:
|
||
type: string
|
||
description: File format.
|
||
oneOf:
|
||
-
|
||
title: Fixed width format
|
||
required: [ fields ]
|
||
properties:
|
||
class:
|
||
enum:
|
||
- S
|
||
- V
|
||
type:
|
||
const: fixed-width
|
||
fields:
|
||
type: object
|
||
description: A dictionary of property names and their definitions.
|
||
required: [ line_name, point_number, easting, northing ]
|
||
properties:
|
||
line_name:
|
||
allOf:
|
||
- description: Line name
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: int
|
||
- $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
|
||
point_number:
|
||
allOf:
|
||
- description: Point number
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: int
|
||
- $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
|
||
easting:
|
||
allOf:
|
||
- description: Easting grid value
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: float
|
||
- $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
|
||
northing:
|
||
allOf:
|
||
- description: Northing grid value
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: float
|
||
- $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
|
||
patternProperties:
|
||
"^.+$":
|
||
$ref: "#/components/schemas/FixedStringDecoderFieldDefinition"
|
||
-
|
||
title: Standard formats
|
||
properties:
|
||
class:
|
||
enum:
|
||
- S
|
||
- V
|
||
type:
|
||
enum:
|
||
- sps1
|
||
- sps2.1
|
||
- p190
|
||
-
|
||
title: CSV
|
||
properties:
|
||
class:
|
||
enum:
|
||
- S
|
||
- V
|
||
type:
|
||
const: csv
|
||
delimiter:
|
||
$ref: "#/components/schemas/DelimitedStringDecoderDelimiterDefinition"
|
||
fields:
|
||
type: object
|
||
description: A dictionary of property names and their definitions.
|
||
required: [ line_name, point_number, easting, northing ]
|
||
properties:
|
||
line_name:
|
||
allOf:
|
||
- description: Line name
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: int
|
||
- $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
|
||
point_number:
|
||
allOf:
|
||
- description: Point number
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: int
|
||
- $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
|
||
easting:
|
||
allOf:
|
||
- description: Easting grid value
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: float
|
||
- $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
|
||
northing:
|
||
allOf:
|
||
- description: Northing grid value
|
||
-
|
||
properties:
|
||
type:
|
||
type: string
|
||
const: float
|
||
- $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
|
||
patternProperties:
|
||
"^.+$":
|
||
$ref: "#/components/schemas/DelimitedStringDecoderFieldDefinition"
|
||
-
|
||
title: Sail lines
|
||
properties:
|
||
class:
|
||
description: Sail lines preplot class
|
||
const: saillines
|
||
type:
|
||
const: x-sl+csv
|
||
-
|
||
title: Legacy format
|
||
deprecated: true
|
||
required: [ format ]
|
||
properties:
|
||
class:
|
||
enum:
|
||
- S
|
||
- V
|
||
type:
|
||
const: sps
|
||
format:
|
||
type: object
|
||
description: Fields format specification
|
||
required: [ widths, names, types ]
|
||
properties:
|
||
widths:
|
||
type: array
|
||
description: Array of field widths. A positive value denotes the width of the next valid field; a negative value skips that number of characters.
|
||
items:
|
||
- integer
|
||
names:
|
||
type: array
|
||
description: |
|
||
Array of field names. Must contain at least the following values:
|
||
|
||
- `line_name`
|
||
- `point_number`
|
||
- `easting`
|
||
- `northing`
|
||
|
||
It may contain additional fields, but those will not be interpreted or used by Dougal.
|
||
items:
|
||
- string
|
||
types:
|
||
type: array
|
||
description: |
|
||
Array of field types. Must be one of the following:
|
||
|
||
- `str`
|
||
- `int`
|
||
- `float`
|
||
items:
|
||
-
|
||
type: string
|
||
enum:
|
||
- str
|
||
- int
|
||
- float
|
||
|
||
|
||
PlannerSettings:
|
||
description: Planner settings.
|
||
type: object
|
||
properties:
|
||
defaultLineChangeDuration:
|
||
type: number
|
||
description: Default line change time (minutes)
|
||
defaultAcquisitionSpeed:
|
||
type: number
|
||
description: Default line acquisition speed (knots)
|
||
overlapBefore:
|
||
type: integer
|
||
description: Shots to overlap before a reshoot.
|
||
overlapAfter:
|
||
type: integer
|
||
description: Shots to overlap after a reshoot.
|
||
|
||
# LineNameInfo: TODO
|
||
|
||
LineNameProperty:
|
||
description: Description of a property available to include in a line name
|
||
type: object
|
||
properties:
|
||
summary:
|
||
description: A short name for the property
|
||
type: string
|
||
description:
|
||
description: A longer text describing the property
|
||
type: string
|
||
type:
|
||
description: The property's type
|
||
type: string
|
||
enum:
|
||
- boolean
|
||
- number
|
||
- text
|
||
format:
|
||
description: An optional format further constraining the type
|
||
|
||
LineNameProperties:
|
||
description: Properties available from the system to include in a line name
|
||
type: object
|
||
properties:
|
||
line_number:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
sequence_number:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
original_sequence:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
pass_number:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
is_prime:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
is_reshoot:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
is_infill:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
direction:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
is_incrementing:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
text:
|
||
$ref: "#/components/schemas/LineNameProperty"
|
||
|
||
LineNameBuilderField:
|
||
description: Describes one of the elements making up a line name
|
||
type: object
|
||
properties:
|
||
item:
|
||
description: |
|
||
Field item type.
|
||
|
||
Note that `text` is a special item type that
|
||
requires a value as part of its definition,
|
||
whereas for all other types a value is provided
|
||
by the system.
|
||
type: string
|
||
enum:
|
||
- line_number
|
||
- sequence_number
|
||
- original_sequence
|
||
- pass_number
|
||
- is_prime
|
||
- is_reshoot
|
||
- is_infill
|
||
- direction
|
||
- is_incrementing
|
||
- text
|
||
when:
|
||
description: |
|
||
For boolean types, only process this field if the value
|
||
matches. If `undefined`, the field is processed regardless
|
||
of the value
|
||
type: boolean
|
||
default: undefined
|
||
offset:
|
||
description: Position in the line name where to insert this field
|
||
type: number
|
||
format: integer
|
||
min: 0
|
||
length:
|
||
description: Number of characters that this field takes up
|
||
type: number
|
||
format: integer
|
||
min: 1
|
||
value:
|
||
description: |
|
||
A default value for this field, or a value to be
|
||
used in the event of an item of type `text`.
|
||
type: string
|
||
pad_side:
|
||
description: |
|
||
Side to on which to apply padding to the field if
|
||
the value is shorter than `length`
|
||
type: string
|
||
enum:
|
||
- left
|
||
- right
|
||
pad_string:
|
||
description: Character (or string) to use for padding
|
||
type: string
|
||
default: " "
|
||
scale_offset:
|
||
description: |
|
||
For numeric values, an offset to apply to the value
|
||
provided by the system. The value is scaled first
|
||
and then offset
|
||
type: number
|
||
default: 0
|
||
scale_multiplier:
|
||
description: |
|
||
For numeric values, a multiplier to apply to the
|
||
value provided by the system. The value is scaled
|
||
first and then offset.
|
||
type: number
|
||
default: 1
|
||
|
||
LineNameBuilder:
|
||
description: Line name specification
|
||
type: object
|
||
properties:
|
||
fields:
|
||
description: List of fields making up the line
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/LineNameBuilderField"
|
||
|
||
|
||
ASAQCSettings:
|
||
description: Configuration details for making requests to Equinor's ASAQC <abbr title="Application Programming Interface">API</abbr>.
|
||
type: object
|
||
required: [ id, imo, mmsi, subscriptionKey ]
|
||
properties:
|
||
id:
|
||
type: integer
|
||
description: The ID for this project in ASAQC. This value must be obtained from Equinor.
|
||
imo:
|
||
type: integer
|
||
description: The acquisition vessel's IMO ship identification number.
|
||
mmsi:
|
||
type: integer
|
||
description: >
|
||
The acquisition vessel's current (at the time of acquiring the relevant project)
|
||
<abbr title="Maritime Mobile Service Identity">MMSI</abbr>.
|
||
subscriptionKey:
|
||
type: string
|
||
description: |
|
||
API subscription key, provided by Equinor, which grants access to the API.
|
||
|
||
FilePath:
|
||
description: Filesystem path.
|
||
type: string
|
||
|
||
|
||
ProjectDefinition:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: The project ID. Used throughout the API in the `{project}` path parameter. It must be unique within a Dougal installation.
|
||
name:
|
||
type: string
|
||
description: Project name.
|
||
groups:
|
||
type: array
|
||
description: A list of *groups* to which the project is assigned. Projects in the same group are expected to share the same, or essentially the same, preplots and acquisition characteristics so that they can be reasonably compared to each other, e.g., for repeatability.
|
||
items:
|
||
type: string
|
||
organisations:
|
||
type: object
|
||
description: A list of client organisations associated with this project and their level of access
|
||
epsg:
|
||
type: string
|
||
description: The EPSG code of the project's CRS, as recognised by PostGIS.
|
||
binning:
|
||
allOf:
|
||
- $ref: "#/components/schemas/BinningGridDefinition"
|
||
- description: The project's binning grid definition.
|
||
archived:
|
||
type: boolean
|
||
description: Indicate whether this is an archived project. Archived projects are not scanned for changes.
|
||
default: false
|
||
preplots:
|
||
description: |
|
||
Preplot definitions.
|
||
|
||
<details><summary>Details:</summary>
|
||
|
||
Source and vessel points may be imported from files in standard formats (SPS v1, SPS v2.1, P1/90), in other fixed-width formats, or character-delimited formats (CSV).
|
||
|
||
Additionally, Dougal supports importing ancillary sail line information from especially formatted CSV files.
|
||
|
||
The class of data to be imported is communicated in the `class` attribute and can be one of:
|
||
|
||
- `S` for source points
|
||
- `V` for vessel points
|
||
- `saillines` for ancillary sail line information
|
||
|
||
And the file format is given in the `type` attribute, as one of:
|
||
|
||
- `sps`: The legacy value for all fixed-width formats
|
||
- `fixed-width`: A general purpose fixed-width importer, for files that do not conform to a standard format.
|
||
- `sps1`: SPS version 1 files.
|
||
- `sps2.1`: SPS version 2.1 files.
|
||
- `p190`: P1/90 files.
|
||
- `p111`: P1/11 files.
|
||
- `csv`: CSV-formatted files (supports arbitrary delimiters).
|
||
- `saillines`: A CSV file with a specific format.
|
||
</details>
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PreplotFileSpecification"
|
||
online:
|
||
description: Online data configuration.
|
||
type: object
|
||
properties:
|
||
line:
|
||
description: Line name details.
|
||
type: object
|
||
properties:
|
||
pattern:
|
||
allOf:
|
||
- deprecated: true
|
||
- $ref: "#/components/schemas/RegExpPatternDefinition"
|
||
- description: |
|
||
Line name format.
|
||
|
||
The line details should contain at least the following capture groups:
|
||
|
||
- `line`: The preplot sailline name.
|
||
- `sequence`: The sequence number.
|
||
|
||
It *may* also contain zero or more of these:
|
||
|
||
- `direction`: The line direction code (indicates whether the line is being
|
||
shot low-to-high or high-to-low).
|
||
- `attempt`: The attempt number / code.
|
||
raw:
|
||
description: Raw data configuration.
|
||
type: object
|
||
properties:
|
||
p111:
|
||
allOf:
|
||
- $ref: "#/components/schemas/DataFilePathSpecification"
|
||
- description: Raw P1/11 file paths and names.
|
||
p190:
|
||
allOf:
|
||
- $ref: "#/components/schemas/DataFilePathSpecification"
|
||
- description: Raw P1/90 file paths and names **(not well supported – use P1/11 if possible)**.
|
||
source:
|
||
description: Energy source data configuration
|
||
type: object
|
||
properties:
|
||
smsrc:
|
||
description: Configuration specific to Smartsource gun controllers
|
||
type: object
|
||
properties:
|
||
header:
|
||
allOf:
|
||
- $ref: "#/components/schemas/DataFilePathSpecification"
|
||
- description: |
|
||
Smartsource gun controller header files.
|
||
|
||
These files contain sensor information from the guns, such as filling times and pressures, firing delays, system errors, etc.
|
||
segy:
|
||
allOf:
|
||
- $ref: "#/components/schemas/DataFilePathSpecification"
|
||
- description: |
|
||
Smartsource SEG-Y files.
|
||
|
||
These files contain near field hydrophone data for an entire sequence.
|
||
ntbp:
|
||
allOf:
|
||
- $ref: "#/components/schemas/RegExpPatternDefinition"
|
||
- description: |
|
||
Regular expression used to identify <abbr title="Not To Be Processed">NTBP</abbr>
|
||
sequences.
|
||
|
||
If the (full) path to a raw P1/11 or P1/90 file matches this regular expression,
|
||
the sequence is considered to be NTBP and any final data will be ignored.
|
||
planner:
|
||
$ref: "#/components/schemas/PlannerSettings"
|
||
labels:
|
||
description: |
|
||
List of project labels. These labels complement the system's default labels.
|
||
In the event that a label name matches a system label, the latter gets redefined
|
||
in the context of this project only.
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
events:
|
||
description: Event settings.
|
||
type: object
|
||
properties:
|
||
presetRemarks:
|
||
$ref: "#/components/schemas/PresetRemarksList"
|
||
cloud:
|
||
description: |
|
||
Cloud API settings.
|
||
|
||
Entries in this section provide information that Dougal needs in order to communicate with remote APIs.
|
||
type: object
|
||
properties:
|
||
asaqc:
|
||
$ref: "#/components/schemas/ASAQCSettings"
|
||
|
||
|
||
|
||
|
||
ProjectSummary:
|
||
type: object
|
||
properties:
|
||
pid:
|
||
type: string
|
||
description: The project ID. Used throughout the API in the `{project}` path parameter.
|
||
name:
|
||
type: string
|
||
description: Project name.
|
||
schema:
|
||
type: string
|
||
description: The internal namespace for a project used by the backend database.
|
||
lines:
|
||
type: integer
|
||
description: Number of preplot lines.
|
||
total:
|
||
type: integer
|
||
description: Number of preplot points.
|
||
virgin:
|
||
type: integer
|
||
description: Number of preplot points that have not been acquired at least once.
|
||
prime:
|
||
type: integer
|
||
description: Number of preplot points acquired exactly once.
|
||
other:
|
||
type: integer
|
||
description: Number of preplot points acquired more than once (reshoots, overlaps, …)
|
||
ntba:
|
||
type: integer
|
||
description: Number of preplot points marked as *NTBA* (Not To Be Acquired). This points do not count towards the total of remaining points.
|
||
remaining:
|
||
type: integer
|
||
description: Number of points remaining to be acquired.
|
||
fsp:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Shotpoint"
|
||
- description: First valid shotpoint of the project.
|
||
lsp:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Shotpoint"
|
||
- description: Last final shotpoint acquired so far.
|
||
seq_raw:
|
||
type: integer
|
||
description: Number of sequences acquired.
|
||
seq_final:
|
||
type: integer
|
||
description: Number of sequences processed.
|
||
prod_duration:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Duration"
|
||
- description: Total production time so far (processed lines only).
|
||
prod_distance:
|
||
type: number
|
||
description: Total production distance in metres (processed lines only).
|
||
shooting_rate:
|
||
type: number
|
||
description: Average time between shots in production, in seconds.
|
||
|
||
PreplotLine:
|
||
type: object
|
||
properties:
|
||
line:
|
||
type: integer
|
||
description: Line number.
|
||
fsp:
|
||
type: integer
|
||
description: First point number.
|
||
lsp:
|
||
type: integer
|
||
description: Last point number.
|
||
num_points:
|
||
type: integer
|
||
description: Number of points in this line.
|
||
na:
|
||
type: integer
|
||
description: Number of points in this line which have not been acquired and processed at least once (virgin points).
|
||
tba:
|
||
type: integer
|
||
description: Number of virgin points in this line which do not have their `ntba` flag set.
|
||
length:
|
||
type: number
|
||
description: Length of the line in metres.
|
||
azimuth:
|
||
type: number
|
||
description: Grid azimuth of the line, in sexagesimal degrees.
|
||
incr:
|
||
type: boolean
|
||
description: "Line direction: `true` if the line is meant to be shot from low to high point numbers, `false` otherwise."
|
||
remarks:
|
||
type: string
|
||
description: Arbitrary text entered by the user.
|
||
ntba:
|
||
type: boolean
|
||
description: Not to be acquired flag. If `true`, all the points in this line are ignored in production statistics.
|
||
meta:
|
||
type: object
|
||
description: Arbitrary JSON data associated with this shotpoint.
|
||
|
||
|
||
Shotpoint:
|
||
type: object
|
||
properties:
|
||
sequence:
|
||
type: integer
|
||
description: Sequence number.
|
||
line:
|
||
type: integer
|
||
description: Line number.
|
||
point:
|
||
type: integer
|
||
description: Point number.
|
||
objref:
|
||
type: integer
|
||
description: P1/11 `objref` value. References the source used during acquisition.
|
||
tstamp:
|
||
type: string
|
||
format: date-time
|
||
description: Acquisition timestamp.
|
||
hash:
|
||
type: string
|
||
description: This value uniquely identifies a version of the file from where the shotpoint data was read.
|
||
geometry:
|
||
allOf:
|
||
- $ref: "#/components/schemas/GeoJSONPoint"
|
||
- description: WGS84 position of the shotpoint.
|
||
meta:
|
||
type: object
|
||
description: Arbitrary JSON data associated with this shotpoint.
|
||
|
||
Sequence:
|
||
type: object
|
||
properties:
|
||
sequence:
|
||
type: integer
|
||
description: Sequence number.
|
||
line:
|
||
type: integer
|
||
description: Sail line number.
|
||
fsp:
|
||
type: integer
|
||
description: First raw data shotpoint.
|
||
lsp:
|
||
type: integer
|
||
description: Last raw data shotpoint. May be `null` if the sequence is still being acquired.
|
||
nullable: true
|
||
fsp_final:
|
||
type: integer
|
||
description: First processed data shotpoint. May be `null` if there is no processed data.
|
||
nullable: true
|
||
lsp_final:
|
||
type: integer
|
||
description: Last processed data shotpoint. May be `null` if there is no processed data.
|
||
nullable: true
|
||
ts0:
|
||
type: string
|
||
format: date-time
|
||
description: Timestamp of the first raw shotpoint.
|
||
ts1:
|
||
type: string
|
||
format: date-time
|
||
description: Timestamp of the last raw shotpoint. May be `null` if the sequence is still being acquired.
|
||
nullable: true
|
||
ts0_final:
|
||
type: string
|
||
format: date-time
|
||
description: Timestamp of the first processed shotpoint. May be `null` if there is no processed data.
|
||
nullable: true
|
||
ts1_final:
|
||
type: string
|
||
format: date-time
|
||
description: Timestamp of the last processed shotpoint. May be `null` if there is no processed data.
|
||
nullable: true
|
||
duration:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Duration"
|
||
- description: Interval between the first and last raw shotpoints.
|
||
duration_final:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Duration"
|
||
- description: Interval between the first and last processed shotpoints.
|
||
num_preplots:
|
||
type: integer
|
||
description: Number of points in this sequence having a corresponding preplot.
|
||
num_points:
|
||
type: integer
|
||
description: >
|
||
Total number of points in this sequence. This value is to be interpreted differently depending on the `status` attribute:
|
||
|
||
* `online`: Number of points acquired so far
|
||
|
||
* `raw`: Number of raw shotpoints acquired
|
||
|
||
* `final`: Number of final shotpoints
|
||
|
||
* `ntbp`: This will be either the same as `raw` or `final` depending on whether or not the sequence has been processed. If a sequence has been processed, some or all of the `*_final` attributes will be non-null.
|
||
missing_shots:
|
||
type: integer
|
||
description: Number of missing shots. A missing shot is counted as a preplot point that falls between `fsp` and `lsp` and doesn't have a corresponding shotpoint in this sequence.
|
||
length:
|
||
type: number
|
||
description: Distance between `fsp_final` and `lsp_final` if both are non-null, otherwise, it's the distance between `fsp` and `lsp`. In metres.
|
||
azimuth:
|
||
type: number
|
||
description: Azimuth corresponding to `length`, in sexagesimal degrees.
|
||
remarks:
|
||
type: string
|
||
description: Arbitrary user-entered text for the raw sequence data.
|
||
remarks_final:
|
||
type: string
|
||
description: Arbitrary user-entered text for the processed sequence data.
|
||
status:
|
||
type: string
|
||
enum:
|
||
- online
|
||
- raw
|
||
- final
|
||
- ntbp
|
||
description: >
|
||
Sequence status.
|
||
|
||
* `online`: the sequence is being acquired, or has recently finished but no raw data P1 has been seen yet.
|
||
|
||
* `raw`: the sequence has been acquired but not yet processed.
|
||
|
||
* `final`: a processed P1 corresponding to this sequence has been found and successfully imported.
|
||
|
||
* `ntbp`: the sequence was marked as ‘not to be processed’.
|
||
|
||
PlannedSequence:
|
||
type: object
|
||
properties:
|
||
sequence:
|
||
type: integer
|
||
description: Planned sequence number.
|
||
line:
|
||
type: integer
|
||
description: Preplot line number.
|
||
fsp:
|
||
type: integer
|
||
description: First planned shot point.
|
||
lsp:
|
||
type: integer
|
||
description: Last planned shot point.
|
||
ts0:
|
||
type: string
|
||
format: date-time
|
||
description: Estimated timestamp of the first shot.
|
||
ts1:
|
||
type: string
|
||
format: date-time
|
||
description: Estimated timestamp of the last shot.
|
||
name:
|
||
type: string
|
||
description: Acquisition line name.
|
||
remarks:
|
||
type: string
|
||
description: Arbitrary user-entered text.
|
||
meta:
|
||
type: object
|
||
description: Arbitrary JSON data associated with this planned sequence.
|
||
duration:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Duration"
|
||
- readOnly: true
|
||
- description: Interval between `ts0` and `ts1`.
|
||
num_points:
|
||
type: integer
|
||
readOnly: true
|
||
description: Number of shots in the planned sequence.
|
||
length:
|
||
type: number
|
||
readOnly: true
|
||
description: Length of the planned sequence, in metres.
|
||
azimuth:
|
||
type: number
|
||
readOnly: true
|
||
description: Azimuth of the planned sequence.
|
||
class:
|
||
type: string
|
||
enum: [ "V" ]
|
||
readOnly: true
|
||
description: Planned sequence line type, always `"V"`, meaning this is a sail line.
|
||
geometry:
|
||
allOf:
|
||
- $ref: "#/components/schemas/GeoJSONLinestring"
|
||
- readOnly: true
|
||
- description: Geometry of the planned line, as a GeoJSON linestring.
|
||
|
||
EventNew:
|
||
description: >
|
||
Information of interest for production, processing, QC, reporting or other purposes.
|
||
|
||
Events can capture both line related data (line log) referenced by sequence and point,
|
||
or general data (daily log) referenced by timestamp.
|
||
|
||
Event entries have a textual description and an optional set of labels to help categorise
|
||
the event, as well as metadata which can include a geographic position for the event.
|
||
|
||
A history of event modifications and deletions is kept by the system. In fact, an `Event` object
|
||
is merely an instance of `EventUniqueEdit` which is current at a given point in time.
|
||
type: object
|
||
properties:
|
||
tstamp:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: Event timestamp.
|
||
sequence:
|
||
type: number
|
||
nullable: true
|
||
description: Event sequence, if applicable.
|
||
point:
|
||
type: number
|
||
nullable: true
|
||
description: Event point, if applicable.
|
||
remarks:
|
||
type: string
|
||
description: Event textual remarks.
|
||
labels:
|
||
type: array
|
||
items: string
|
||
description: Labels applied to this event.
|
||
meta:
|
||
description: Event metadata.
|
||
type: object
|
||
properties:
|
||
geometry:
|
||
allOf:
|
||
- $ref: "#/components/schemas/GeoJSONPoint"
|
||
- description: Event geometry. Typically the location where the event occurred.
|
||
readonly:
|
||
type: boolean
|
||
readOnly: true
|
||
description: >
|
||
Flag to indicate that this event is read-only. It cannot be edited by the user or deleted. Typically this concerns system-generated events such as QC results or midnight shots.
|
||
additionalProperties: true
|
||
|
||
EventIDAbstract:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: number
|
||
description: Event ID.
|
||
|
||
|
||
EventUIDAbstract:
|
||
type: object
|
||
properties:
|
||
uid:
|
||
type: number
|
||
description: Event instance unique ID. When an event is modified, the new entry acquires a different `uid` while keeping the same `id` as the original event.
|
||
|
||
|
||
EventAbstract:
|
||
allOf:
|
||
-
|
||
$ref: "#/components/schemas/EventIDAbstract"
|
||
-
|
||
$ref: "#/components/schemas/EventNew"
|
||
|
||
Event:
|
||
allOf:
|
||
-
|
||
$ref: "#/components/schemas/EventAbstract"
|
||
-
|
||
type: object
|
||
properties:
|
||
has_edits:
|
||
type: boolean
|
||
description: >
|
||
Flag to indicate that the event has been edited. The edit history can be retrieved via the relevant endpoint.
|
||
|
||
EventUniqueEdit:
|
||
allOf:
|
||
-
|
||
description: |
|
||
A unique instance of an event, with information about its time of applicability.
|
||
|
||
For the first instance of an event, the `id` and `uid` are equal. When an edit is made,
|
||
the `uid` changes while the `id` stays the same. If an event is deleted, the latest
|
||
`EventUniqueEdit` has its end of validity timestamp set to deletion time. This means that
|
||
events can be undeleted.
|
||
- $ref: "#/components/schemas/EventAbstract"
|
||
-
|
||
type: object
|
||
properties:
|
||
uid:
|
||
type: number
|
||
readOnly: true
|
||
description: Unique ID of this particular instance of the event. Equals `id` if the event has not been edited.
|
||
validity:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
minItems: 4
|
||
maxItems: 4
|
||
description: |
|
||
Temporal validity of this instance of the event. An array where:
|
||
|
||
* The first element if one of `[` or `(` to indicate whether it is an open or closed interval.
|
||
* The second element is either an ISO-8601 timestamp or `null`. The latter indicates -∞.
|
||
* The third element is either an ISO-8601 timestamp or `null`. The latter indicates +∞. These are the events returned by endpoints that do not concern themselves with event history.
|
||
* The fourth element is one of `]` or `)`. As before, it indicates either an open or closed interval.
|
||
|
||
EventChangesIsDeletedAbstract:
|
||
type: object
|
||
properties:
|
||
is_deleted:
|
||
type: boolean
|
||
description: >
|
||
Flag to indicate whether this event or event instance (depending on the presence of a `uid` attribute) has been deleted.
|
||
|
||
EventChangesIsDeletedTrue:
|
||
allOf:
|
||
-
|
||
$ref: "#/components/schemas/EventChangesIsDeletedAbstract"
|
||
-
|
||
type: object
|
||
properties:
|
||
is_deleted:
|
||
const: true
|
||
|
||
EventChangesModified:
|
||
description: An event modification.
|
||
allOf:
|
||
-
|
||
$ref: "#/components/schemas/EventAbstract"
|
||
-
|
||
$ref: "#/components/schemas/EventChangesIsDeletedAbstract"
|
||
|
||
EventChangesDeleted:
|
||
description: |
|
||
Identification of a deleted event or event instance.
|
||
|
||
**Note:** the details of the deleted event are not included, only its `id` and `uid`.
|
||
allOf:
|
||
-
|
||
$ref: "#/components/schemas/EventIDAbstract"
|
||
-
|
||
$ref: "#/components/schemas/EventUIDAbstract"
|
||
-
|
||
$ref: "#/components/schemas/EventChangesIsDeletedTrue"
|
||
|
||
EventChanges:
|
||
description: List of event changes since the given epoch.
|
||
type: array
|
||
items:
|
||
anyOf:
|
||
-
|
||
$ref: "#/components/schemas/EventChangesDeleted"
|
||
-
|
||
$ref: "#/components/schemas/EventChangesModified"
|
||
|
||
|
||
SeisExportEntryFSP:
|
||
type: object
|
||
properties:
|
||
EntryType:
|
||
type: string
|
||
enum:
|
||
- Start of line recording
|
||
nullable: true
|
||
EntryTypeId:
|
||
type: integer
|
||
enum:
|
||
- 3000
|
||
Comment:
|
||
type: string
|
||
nullable: true
|
||
Heading:
|
||
type: number
|
||
IsReshoot:
|
||
type: boolean
|
||
IsUndershoot:
|
||
type: boolean
|
||
LineNumber:
|
||
type: string
|
||
LineType:
|
||
type: string
|
||
enum:
|
||
- Prime
|
||
- Infill
|
||
ShotPointId:
|
||
type: integer
|
||
Time:
|
||
type: string
|
||
format: date-time
|
||
|
||
SeisExportEntryLSP:
|
||
type: object
|
||
properties:
|
||
EntryType:
|
||
type: string
|
||
enum:
|
||
- End of line recording
|
||
nullable: true
|
||
EntryTypeId:
|
||
type: integer
|
||
enum:
|
||
- 3007
|
||
Comment:
|
||
type: string
|
||
nullable: true
|
||
ShotPointId:
|
||
type: integer
|
||
Time:
|
||
type: string
|
||
format: date-time
|
||
IsNTBP:
|
||
type: boolean
|
||
LineStatus:
|
||
type: string
|
||
enum:
|
||
- Complete
|
||
- Incomplete
|
||
- Pending
|
||
|
||
SeisExportEntry:
|
||
type: object
|
||
properties:
|
||
EntryType:
|
||
type: string
|
||
enum:
|
||
- Start good
|
||
- Start charged
|
||
- Midnight
|
||
- End charged
|
||
- End good
|
||
- Last good Full Fold
|
||
- Last charged Full Fold
|
||
- Start NTBP
|
||
- End NTBP
|
||
nullable: true
|
||
EntryTypeId:
|
||
type: integer
|
||
enum:
|
||
- 3001
|
||
- 3002
|
||
- 3003
|
||
- 3005
|
||
- 3006
|
||
- 3008
|
||
- 3009
|
||
- 3019
|
||
- 3020
|
||
Comment:
|
||
type: string
|
||
nullable: true
|
||
ShotPointId:
|
||
type: integer
|
||
Time:
|
||
type: string
|
||
format: date-time
|
||
|
||
|
||
SeisExport:
|
||
type: object
|
||
properties:
|
||
DglProjectId:
|
||
type: string
|
||
Sequences:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
SequenceNumber:
|
||
type: integer
|
||
Entries:
|
||
type: array
|
||
items:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/SeisExportEntryFSP"
|
||
- $ref: "#/components/schemas/SeisExportEntryLSP"
|
||
- $ref: "#/components/schemas/SeisExportEntry"
|
||
DglNumPoints:
|
||
type: integer
|
||
DglNumMissing:
|
||
type: integer
|
||
DglLength:
|
||
type: number
|
||
|
||
|
||
NavData:
|
||
type: object
|
||
properties:
|
||
_received:
|
||
type: string
|
||
format: date-time
|
||
description: Moment when the data item was received by the Dougal system
|
||
_online:
|
||
type: boolean
|
||
description: Whether a line is being acquired
|
||
_latency:
|
||
type: integer
|
||
description: If the data item has a timestamp recognisable by Dougal, difference between that timestamp and `_received`
|
||
_sequence:
|
||
oneOf:
|
||
- type: string
|
||
- type: integer
|
||
description: Sequence number (only present when `_online` is `true`)
|
||
_line:
|
||
type: integer
|
||
description: Line number (only present when `_online` is `true`)
|
||
_point:
|
||
type: integer
|
||
description: Point number (only present when `_online` is `true`)
|
||
_schema:
|
||
type: string
|
||
description: Internal database reference to the current project (only present when `_online` is `true`)
|
||
|
||
|
||
QueueRequestASAQC:
|
||
description: >
|
||
Parameters of an ASAQC transfer item.
|
||
type: object
|
||
required: [ "project", "sequence", "mimetype" ]
|
||
properties:
|
||
project:
|
||
type: string
|
||
description: Project ID.
|
||
sequence:
|
||
type: integer
|
||
description: Sequence number.
|
||
example:
|
||
{
|
||
"project": "eq21205",
|
||
"sequence": 55
|
||
}
|
||
|
||
|
||
QueueItem:
|
||
description: Information about an item in the transfers queue
|
||
type: object
|
||
properties:
|
||
item_id:
|
||
type: integer
|
||
description: The unique ID of this queue item.
|
||
queue_id:
|
||
type: integer
|
||
description: The ID of the queue that this item belongs to.
|
||
status:
|
||
type: string
|
||
enum: [ "queued", "cancelled", "failed", "sent" ]
|
||
description: Status of the queue request. Failed transfers may get rescheduled as a new item, in which case `parent_id` will reference the original request.
|
||
payload:
|
||
$ref: "#/components/schemas/QueueRequestASAQC"
|
||
results:
|
||
type: object
|
||
description: Information about the transfer after an attempt has been made. It is non-empty only for items with status `failed` or `sent`.
|
||
properties:
|
||
digest:
|
||
type: object
|
||
description: Cryptographic digest of the transmitted payload.
|
||
properties:
|
||
sha256:
|
||
type: object
|
||
description: SHA-256 digest.
|
||
properties:
|
||
hex:
|
||
type: string
|
||
description: Hexadecimal representation of the SHA-256 hash of the contents of the file that was sent. Can be used to check, with a high degree of confidence, whether a copy of the file is byte-by-byte the same as the data that was sent.
|
||
response:
|
||
type: object
|
||
description: If the request was successful, the contents of this property are the response body sent by the remote server. If there was an error, the `error` property will be present and may contain details of the problem.
|
||
created_on:
|
||
type: string
|
||
format: date-time
|
||
description: Creation timestamp of this request.
|
||
updated_on:
|
||
type: string
|
||
format: date-time
|
||
description: Last update timestamp of this request.
|
||
not_before:
|
||
type: string
|
||
format: date-time
|
||
description: The request will not be processed before this.
|
||
parent_id:
|
||
type: integer
|
||
description: If this request is a retry of a failed attempt, this item references the ID of the original request.
|
||
example:
|
||
{
|
||
"item_id": 87,
|
||
"status": "sent",
|
||
"payload": {
|
||
"project": "eq21205",
|
||
"sequence": 55
|
||
},
|
||
"results": [
|
||
{
|
||
"id": "849e8659-953d-466c-8cfc-ad8d615d1ac0",
|
||
"fileName": "1065960055S00000-NavLog.json"
|
||
},
|
||
{
|
||
"id": "517864a7-0981-46c6-8f39-aa53da865de7",
|
||
"fileName": "1065960055S00000-NavLog.pdf"
|
||
}
|
||
],
|
||
"created_on": "2021-10-03T01:47:02.312Z",
|
||
"updated_on": "2021-10-03T01:51:19.656Z",
|
||
"not_before": "1970-01-01T00:00:00.000Z",
|
||
"parent_id": null
|
||
}
|
||
|
||
SoftwareVersion:
|
||
description: Software and component versions
|
||
type: object
|
||
properties:
|
||
name:
|
||
description: Server application name
|
||
type: string
|
||
server:
|
||
description: Server application version
|
||
type: string
|
||
tag:
|
||
description: Server application version control tag
|
||
type: string
|
||
api:
|
||
description: Application program interface version
|
||
type: string
|
||
schema:
|
||
description: Database schema version
|
||
type: string
|
||
db:
|
||
description: |
|
||
Database components.
|
||
*Only shown to users with write access.*
|
||
type: object
|
||
properties:
|
||
version:
|
||
description: Database server description
|
||
type: string
|
||
postgis_version:
|
||
description: PostGIS version number
|
||
type: string
|
||
os:
|
||
description: |
|
||
Operating system information. See the [`/etc/os-release` file description](https://www.freedesktop.org/software/systemd/man/latest/os-release.html#Options) for information on the specific values.
|
||
*Only shown to users with write access.*
|
||
type: object
|
||
properties:
|
||
ID:
|
||
description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#ID=
|
||
type: string
|
||
NAME:
|
||
description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#NAME=
|
||
type: string
|
||
PRETTY_NAME:
|
||
description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#PRETTY_NAME=
|
||
type: string
|
||
VERSION:
|
||
description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#VERSION=
|
||
type: string
|
||
VERSION_ID:
|
||
description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#VERSION_ID=
|
||
type: string
|
||
compatibility:
|
||
description: Version compatibility
|
||
type: array
|
||
items:
|
||
type: object
|
||
description: |
|
||
Compatibility object. Describes the compatibility requirements of the currently running system.
|
||
properties:
|
||
component:
|
||
description: The component being checked.
|
||
type: string
|
||
enum: [ "schema" ]
|
||
current:
|
||
description: Current version number for this component.
|
||
type: string
|
||
wanted:
|
||
description: Wanted version. This uses NodeJS' semantic versioning comparisons. See https://github.com/npm/node-semver#ranges for a description of the syntax.
|
||
type: string
|
||
example:
|
||
{
|
||
"name": "dougal-server-web",
|
||
"server": "0.0.0",
|
||
"tag": "v3-260-g46bb207",
|
||
"api": "0.4.0",
|
||
"schema": "0.4.5",
|
||
"db": {
|
||
"version": "PostgreSQL 14.8 on x86_64-suse-linux-gnu, compiled by gcc (SUSE Linux) 13.2.1 20230803 [revision cc279d6c64562f05019e1d12d0d825f9391b5553], 64-bit",
|
||
"postgis_version": "3.3 USE_GEOS=1 USE_PROJ=1 USE_STATS=1"
|
||
},
|
||
"os": {
|
||
"NAME": "openSUSE Leap",
|
||
"VERSION": "15.4",
|
||
"ID": "opensuse-leap",
|
||
"VERSION_ID": "15.4",
|
||
"PRETTY_NAME": "openSUSE Leap 15.4"
|
||
},
|
||
"compatibility": [
|
||
{
|
||
"current": "0.4.5",
|
||
"wanted": "^0.4.5",
|
||
"component": "schema"
|
||
},
|
||
{
|
||
"current": "0.4.0",
|
||
"wanted": "^0.4.0",
|
||
"component": "api"
|
||
}
|
||
]
|
||
}
|
||
|
||
|
||
ServerDiagnostics:
|
||
description: Server diagnostics information
|
||
type: object
|
||
properties:
|
||
hostname:
|
||
description: Returns the host name of the operating system as a string
|
||
type: string
|
||
memory:
|
||
description: Returns system memory information
|
||
type: object
|
||
properties:
|
||
total:
|
||
description: Returns the total amount of system memory in bytes as an integer.
|
||
type: number
|
||
free:
|
||
description: Returns the amount of free system memory in bytes as an integer.
|
||
type: number
|
||
uptime:
|
||
description: Returns the system uptime in number of seconds.
|
||
type: number
|
||
loadavg:
|
||
description: |
|
||
Returns an array containing the 1, 5, and 15 minute load averages.
|
||
The load average is a measure of system activity calculated by the operating system and expressed as a fractional number.
|
||
type: array
|
||
items:
|
||
type: number
|
||
minItems: 3
|
||
maxItems: 3
|
||
networkInterfaces:
|
||
description: |
|
||
Returns an object containing network interfaces that have been assigned a network address.
|
||
Each key on the returned object identifies a network interface. The associated value is an array of objects that each describe an assigned network address.
|
||
type: object
|
||
additionalProperties:
|
||
description: Interface name
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
address:
|
||
description: The assigned IPv4 or IPv6 address
|
||
type: string
|
||
netmask:
|
||
description: The IPv4 or IPv6 network mask
|
||
type: string
|
||
family:
|
||
description: Either `IPv4` or `IPv6`
|
||
type: string
|
||
mac:
|
||
description: The MAC address of the network interface
|
||
type: string
|
||
internal:
|
||
description: |
|
||
`true` if the network interface is a loopback or similar interface that is not remotely accessible; otherwise `false`
|
||
type: boolean
|
||
cidr:
|
||
description: The assigned IPv4 or IPv6 address with the routing prefix in CIDR notation. If the `netmask` is invalid, this property is set to `null`.
|
||
type: string
|
||
scopeid:
|
||
description: The numeric IPv6 scope ID (only specified when `family` is `IPv6`)
|
||
type: integer
|
||
cpus:
|
||
description: Returns an array of objects containing information about each logical CPU core.
|
||
type: array
|
||
items:
|
||
description:
|
||
type: object
|
||
properties:
|
||
model:
|
||
description: CPU model string
|
||
type: string
|
||
speed:
|
||
description: Current speed in MHz
|
||
type: integer
|
||
times:
|
||
description: CPU usage information
|
||
type: object
|
||
properties:
|
||
user:
|
||
description: The number of milliseconds the CPU has spent in user mode.
|
||
type: integer
|
||
nice:
|
||
description: The number of milliseconds the CPU has spent in nice mode.
|
||
type: integer
|
||
sys:
|
||
description: The number of milliseconds the CPU has spent in sys mode.
|
||
type: integer
|
||
idle:
|
||
description: The number of milliseconds the CPU has spent in idle mode.
|
||
type: integer
|
||
irq:
|
||
description: The number of milliseconds the CPU has spent in irq mode.
|
||
type: integer
|
||
storage:
|
||
description: Returns information about filesystems and storage usage
|
||
type: object
|
||
properties:
|
||
root:
|
||
description: Provides information about the root file system.
|
||
type: object
|
||
properties:
|
||
total:
|
||
description: Total number of bytes
|
||
type: integer
|
||
free:
|
||
description: Free space (in bytes)
|
||
type: integer
|
||
available:
|
||
description: Space available to the Dougal user (in bytes)
|
||
type: integer
|
||
used:
|
||
description: Used space (in bytes)
|
||
type: integer
|
||
usedPercent:
|
||
description: |
|
||
`free` / `available` * 100
|
||
type: number
|
||
data:
|
||
description: Return storage information for each data path accessible to Dougal users via the API
|
||
type: object
|
||
additionalProperties:
|
||
description: The property name is the name the user sees for this subpath.
|
||
type: object
|
||
properties:
|
||
total:
|
||
description: Total number of bytes
|
||
type: integer
|
||
free:
|
||
description: Free space (in bytes)
|
||
type: integer
|
||
available:
|
||
description: Space available to the Dougal user (in bytes)
|
||
type: integer
|
||
used:
|
||
description: Used space (in bytes)
|
||
type: integer
|
||
usedPercent:
|
||
description: |
|
||
`free` / `available` * 100
|
||
type: number
|
||
database:
|
||
description: Returns database space usage information
|
||
type: object
|
||
properties:
|
||
size:
|
||
description: Total size of the PostgreSQL database (in bytes)
|
||
type: integer
|
||
projects:
|
||
description: Individual project information
|
||
type: object
|
||
additionalProperties:
|
||
description: Information about each project. The property name is the project's ID.
|
||
type: object
|
||
properties:
|
||
size:
|
||
description: Size of the storage used by this project (in bytes)
|
||
type: integer
|
||
percent:
|
||
description: Size as a percentage of the entire PostgreSQL used storage
|
||
type: number
|
||
example:
|
||
{
|
||
"hostname": "dougal04",
|
||
"memory": {
|
||
"total": 16324186112,
|
||
"free": 14940069888
|
||
},
|
||
"uptime": 955504.5,
|
||
"loadavg": [
|
||
0.49,
|
||
0.49,
|
||
0.69
|
||
],
|
||
"networkInterfaces": {
|
||
"lo": [
|
||
{
|
||
"address": "127.0.0.1",
|
||
"netmask": "255.0.0.0",
|
||
"family": "IPv4",
|
||
"mac": "00:00:00:00:00:00",
|
||
"internal": true,
|
||
"cidr": "127.0.0.1/8"
|
||
},
|
||
{
|
||
"address": "::1",
|
||
"netmask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
|
||
"family": "IPv6",
|
||
"mac": "00:00:00:00:00:00",
|
||
"internal": true,
|
||
"cidr": "::1/128",
|
||
"scopeid": 0
|
||
}
|
||
],
|
||
"em1": [
|
||
{
|
||
"address": "172.31.135.140",
|
||
"netmask": "255.255.255.0",
|
||
"family": "IPv4",
|
||
"mac": "b8:cb:29:dd:c2:1e",
|
||
"internal": false,
|
||
"cidr": "172.31.135.140/24"
|
||
},
|
||
{
|
||
"address": "fe80::bacb:29ff:fedd:c21e",
|
||
"netmask": "ffff:ffff:ffff:ffff::",
|
||
"family": "IPv6",
|
||
"mac": "b8:cb:29:dd:c2:1e",
|
||
"internal": false,
|
||
"cidr": "fe80::bacb:29ff:fedd:c21e/64",
|
||
"scopeid": 2
|
||
}
|
||
],
|
||
"em2": [
|
||
{
|
||
"address": "172.31.135.12",
|
||
"netmask": "255.255.255.0",
|
||
"family": "IPv4",
|
||
"mac": "b8:cb:29:dd:c2:1f",
|
||
"internal": false,
|
||
"cidr": "172.31.135.12/24"
|
||
},
|
||
{
|
||
"address": "fe80::bacb:29ff:fedd:c21f",
|
||
"netmask": "ffff:ffff:ffff:ffff::",
|
||
"family": "IPv6",
|
||
"mac": "b8:cb:29:dd:c2:1f",
|
||
"internal": false,
|
||
"cidr": "fe80::bacb:29ff:fedd:c21f/64",
|
||
"scopeid": 3
|
||
}
|
||
]
|
||
},
|
||
"cpus": [
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 65874900,
|
||
"nice": 37340,
|
||
"sys": 6784430,
|
||
"idle": 877795820,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 59011560,
|
||
"nice": 45110,
|
||
"sys": 6114070,
|
||
"idle": 886504400,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 52777060,
|
||
"nice": 59160,
|
||
"sys": 5497730,
|
||
"idle": 893863890,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 2292,
|
||
"times": {
|
||
"user": 49464660,
|
||
"nice": 820,
|
||
"sys": 5265370,
|
||
"idle": 897610020,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 47904520,
|
||
"nice": 9410,
|
||
"sys": 5337240,
|
||
"idle": 899077360,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 40433680,
|
||
"nice": 54890,
|
||
"sys": 4350020,
|
||
"idle": 906785860,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 24040170,
|
||
"nice": 17370,
|
||
"sys": 3533740,
|
||
"idle": 924358390,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 32668650,
|
||
"nice": 39340,
|
||
"sys": 4629000,
|
||
"idle": 915014220,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 39244360,
|
||
"nice": 9000,
|
||
"sys": 5110890,
|
||
"idle": 908206780,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 42595880,
|
||
"nice": 14420,
|
||
"sys": 5186740,
|
||
"idle": 904591700,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 44487620,
|
||
"nice": 43310,
|
||
"sys": 5266430,
|
||
"idle": 902752740,
|
||
"irq": 0
|
||
}
|
||
},
|
||
{
|
||
"model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
|
||
"speed": 3400,
|
||
"times": {
|
||
"user": 49013200,
|
||
"nice": 89360,
|
||
"sys": 5229000,
|
||
"idle": 896654340,
|
||
"irq": 0
|
||
}
|
||
}
|
||
],
|
||
"storage": {
|
||
"root": {
|
||
"total": 981132492800,
|
||
"free": 955562377216,
|
||
"available": 905648078848,
|
||
"used": 25570115584,
|
||
"usedPercent": 2.6061837490497184
|
||
},
|
||
"data": {
|
||
"Nav": {
|
||
"total": 2199023255552,
|
||
"free": 1895510478848,
|
||
"available": 1895510478848,
|
||
"used": 303512776704,
|
||
"usedPercent": 13.802163116633892
|
||
},
|
||
"Mech": {
|
||
"total": 1099511627776,
|
||
"free": 641156898816,
|
||
"available": 641156898816,
|
||
"used": 458354728960,
|
||
"usedPercent": 41.687119752168655
|
||
},
|
||
"Client": {
|
||
"total": 1099511627776,
|
||
"free": 1062877327360,
|
||
"available": 1062877327360,
|
||
"used": 36634300416,
|
||
"usedPercent": 3.331870213150978
|
||
},
|
||
"Backup": {
|
||
"total": 4398046511104,
|
||
"free": 3328588230656,
|
||
"available": 3328588230656,
|
||
"used": 1069458280448,
|
||
"usedPercent": 24.31666599586606
|
||
}
|
||
}
|
||
},
|
||
"database": {
|
||
"size": 8437662499,
|
||
"projects": {
|
||
"eq21200": {
|
||
"size": 442359808,
|
||
"percent": 5.242681940080287
|
||
},
|
||
"eq22200": {
|
||
"size": 174219264,
|
||
"percent": 2.064781140756078
|
||
},
|
||
"eq22205": {
|
||
"size": 140255232,
|
||
"percent": 1.6622522175617065
|
||
},
|
||
"eq23200": {
|
||
"size": 185573376,
|
||
"percent": 2.199345802489652
|
||
},
|
||
"eq23205": {
|
||
"size": 319479808,
|
||
"percent": 3.786354432141171
|
||
},
|
||
"eq24200": {
|
||
"size": 161128448,
|
||
"percent": 1.9096337169102975
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
AbstractOrganisationAccess:
|
||
description: Access rights for a given organisation. The property name is used as the organisation's name.
|
||
type: object
|
||
properties:
|
||
read:
|
||
type: boolean
|
||
description: Users belonging to this organisation can view / read data from projects which grant `read` access to the organisation's members
|
||
write:
|
||
type: boolean
|
||
description: Users belonging to this organisation can add, change or write data from projects which grant `write` access to the organisation's members
|
||
edit:
|
||
type: boolean
|
||
description: Users belonging to this organisation can manage (e.g., change settings of) projects which grant `edit` access to the organisation's members
|
||
additionalProperties:
|
||
type: boolean
|
||
description: Other operations (e.g., `delete`, `move`, `create`) may be listed here if the need arises
|
||
propertyNames:
|
||
pattern: "^[a-z][a-z_0-9]+$"
|
||
|
||
SimpleUser:
|
||
description: A user with defined access rights over projects
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
readOnly: true
|
||
description: A unique ID for the user, generated by the system
|
||
name:
|
||
type: string
|
||
description: A short name for the user. Note that the name does not have to be unique!
|
||
email:
|
||
type: string
|
||
format: email
|
||
description: An optional email address for this user.
|
||
colour:
|
||
type: string
|
||
description: A colour, in hex form or as a named colour supported by Vuetify, to assist the user with visual self-identification in the user interface.
|
||
active:
|
||
type: boolean
|
||
description: Whether the user is active or not. Inactive users are not able to log in.
|
||
organisations:
|
||
type: object
|
||
description: A list of organisations that the user has access to, and the permitted actions (read, write, edit, etc.)
|
||
additionalProperties:
|
||
$ref: "#/components/schemas/AbstractOrganisationAccess"
|
||
|
||
NamedUser:
|
||
allOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- description: A user identified by a user name and password
|
||
- type: object
|
||
- properties:
|
||
hash:
|
||
type: string
|
||
writeOnly: true
|
||
description: A hash of the user's password
|
||
|
||
NamedUserSelfEditable:
|
||
description: |
|
||
Payload of an edit request of a `NamedUser` made by the user himself.
|
||
Any other attributes will be ignored.
|
||
type: object
|
||
properties:
|
||
email:
|
||
type: string
|
||
format: email
|
||
description: An optional email address for this user.
|
||
colour:
|
||
type: string
|
||
description: A colour, in hex form or as a named colour supported by Vuetify, to assist the user with visual self-identification in the user interface.
|
||
password:
|
||
type: string
|
||
writeOnly: true
|
||
description: A new password for the user
|
||
|
||
|
||
CertificateUser:
|
||
allOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- description: A user identified by a TLS client certificate
|
||
- type: object
|
||
- properties:
|
||
public_key:
|
||
type: string
|
||
description: The user's public key, ASCII armoured
|
||
|
||
|
||
HostUser:
|
||
allOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- description: A user identified by a hostname
|
||
- type: object
|
||
- properties:
|
||
host:
|
||
type: string
|
||
description: >
|
||
Hostname of the client attempting to connect. If matched, the user will be logged in automatically.
|
||
|
||
IPUser:
|
||
allOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- description: A user identified by an IP address. Only IPv4 is supported at this time.
|
||
- type: object
|
||
- properties:
|
||
ip:
|
||
type: string
|
||
description: |
|
||
IP address or subnet of the client attempting to connect. If matched, the user will be logged in automatically.
|
||
|
||
For instance, this will log in as the user `user1` anyone connecting from `192.168.1.10`:
|
||
|
||
```yaml
|
||
ip: 192.168.1.10
|
||
name: user1
|
||
```
|
||
|
||
And this will log in as `guest` anyone on the 192.168.1.0/24 subnet:
|
||
|
||
```yaml
|
||
ip: 192.168.1.0/24
|
||
name: guest
|
||
```
|
||
|
||
More specific address take precedence over less specific ones.
|
||
|
||
User:
|
||
allOf:
|
||
- summary: A user of the system
|
||
- description: |
|
||
Each user has a `name`, a `colour` (used for display purposes and ease of self-identification), an `active` flag (whether the user can log in or not) and a list of `organisations` that the user belongs to.
|
||
|
||
On top of that, there are different kinds of users depending on the method used to identify them. Users may be identified, in order of priority:
|
||
|
||
* By a TLS client certificate that is presented to the server by their browser
|
||
* By a password that they use to log in with
|
||
* By the IP address of their client machine
|
||
* By the host name of their client machine
|
||
|
||
- oneOf:
|
||
- $ref: "#/components/schemas/NamedUser"
|
||
- $ref: "#/components/schemas/CertificateUser"
|
||
- $ref: "#/components/schemas/HostUser"
|
||
- $ref: "#/components/schemas/IPUser"
|
||
|
||
|
||
UserValidationRequest:
|
||
summary: User validation request
|
||
description: A request for the user to validate an action on his profile
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: UUID
|
||
summary: Validation ID
|
||
description: This is the ID of the validation object in the database
|
||
# user:
|
||
# $ref: "#/components/schemas/NamedUser"
|
||
validate:
|
||
type: string
|
||
enum: [ "create", "email", "password" ]
|
||
description: |
|
||
The type of validation to be performed:
|
||
|
||
* `create`: The user entry has been created. The system requires the response to include a password.
|
||
* `email`: The user's email address has been changed (or added). The system expects the user to confirm that the new email address is valid.
|
||
* `password`: The user has forgotten his password. The system requires the response to include a new password.
|
||
|
||
|
||
UserValidationResponsePassword:
|
||
type: object
|
||
description: Creation confirmation or password change
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: UUID
|
||
description: Validation ID
|
||
password:
|
||
type: string
|
||
description: New user password
|
||
|
||
|
||
UserValidationResponseEmail:
|
||
type: object
|
||
description: Change of email
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: UUID
|
||
description: Validation ID
|
||
email:
|
||
type: string
|
||
format: email
|
||
description: New email address
|
||
|
||
|
||
UserValidationResponse:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/UserValidationResponsePassword"
|
||
- $ref: "#/components/schemas/UserValidationResponseEmail"
|
||
|
||
|
||
# UserRole:
|
||
# description:
|
||
#
|
||
# User:
|
||
# description: Information about a user
|
||
# type: object
|
||
# properties:
|
||
# name:
|
||
# type: string
|
||
# description: A user name. Must be unique within a Dougal installation.
|
||
# role:
|
||
# $ref: "#/components/schemas/UserRole"
|
||
|
||
|
||
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
|
||
paths:
|
||
|
||
/config/label:
|
||
get:
|
||
summary: List label definitions
|
||
description: |
|
||
Get a list of all labels defined in this system.
|
||
Note that unlike the [project-level labels endpoint](#tag/project/paths/~1project~1{project}~1label/get),
|
||
only admins may query system-wide labels.
|
||
tags: [ "configuration" ]
|
||
security:
|
||
# TODO
|
||
# Only users with `{"*": {read: true}}` access can query
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
responses:
|
||
"200":
|
||
description: Label definitions
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
post:
|
||
summary: Create one or more labels
|
||
description: |
|
||
This endpoint accepts both JSON and YAML payloads consisting of either a single label object
|
||
or an array of label objects.
|
||
tags: [ "configuration" ]
|
||
security:
|
||
# TODO
|
||
# Only users with `{"*": {edit: true}}` access are authorised
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/Label"
|
||
-
|
||
title: List of Label
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
application/yaml:
|
||
schema:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/Label"
|
||
-
|
||
title: List of Label
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
responses:
|
||
"201":
|
||
description: A new label or set of labels has been created
|
||
"400":
|
||
$ref: "#/components/responses/400"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"409":
|
||
description: |
|
||
The value used for the `name` property conflicts with an existing label.
|
||
If creating multiple labels, this error is returned if *any* of them matches
|
||
an existing label name – in that case, none of the labels in the set will be
|
||
created.
|
||
|
||
/config/label/{name}:
|
||
get:
|
||
summary: Get label definition
|
||
description: |
|
||
Note that unlike the [project-level labels endpoint](#tag/project/paths/~1project~1{project}~1label/get),
|
||
only admins may query system-wide labels.
|
||
tags: [ "configuration" ]
|
||
security:
|
||
# TODO
|
||
# Only users with `{"*": {read: true}}` access are authorised
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
responses:
|
||
"200":
|
||
description: Label definitions
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Label"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
$ref: "#/components/responses/404"
|
||
|
||
put:
|
||
summary: Modify an existing label
|
||
description: |
|
||
Note that this endpoint may be *not* be used to rename an existing label. The `name` attribute is
|
||
expected to match the `name` parameter; if those values don't match, the request will fail with a
|
||
400 error.
|
||
tags: [ "configuration" ]
|
||
security:
|
||
# TODO
|
||
# Only users with `{"*": {edit: true}}` access are authorised
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
parameters:
|
||
-
|
||
name:
|
||
in: path
|
||
description: Label name.
|
||
schema:
|
||
type: string
|
||
required: true
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Label"
|
||
responses:
|
||
"201":
|
||
description: The label has been updated
|
||
"400":
|
||
$ref: "#/components/responses/400"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
$ref: "#/components/responses/404"
|
||
|
||
delete:
|
||
summary: Delete a label
|
||
tags: [ "configuration" ]
|
||
security:
|
||
# TODO
|
||
# Only users with `{"*": {edit: true}}` access are authorised
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
parameters:
|
||
-
|
||
name:
|
||
in: path
|
||
description: Label name.
|
||
schema:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
"204":
|
||
description: The label no longer exists (or has never existed)
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
/project:
|
||
get:
|
||
description: Get list of projects.
|
||
tags: [ "project" ]
|
||
security:
|
||
# TODO
|
||
# Only users with:
|
||
# `{"*": {read: true}}`
|
||
# can access all projects
|
||
# Other users can only access projects for which they have a
|
||
# `{":project": {read: true}}`
|
||
# claim.
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
responses:
|
||
"200":
|
||
description: List of projects
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
pid:
|
||
type: string
|
||
description: The project ID. Used throughout the API in the `{project}` path parameter.
|
||
name:
|
||
type: string
|
||
description: Project name
|
||
schema:
|
||
type: string
|
||
description: The internal namespace for a project used by the backend database.
|
||
groups:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: Zero or more strings, each representing a *group name*. These are used to group together related projects with the same or similar preplots in order to do temporal comparisons and statistics.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
post:
|
||
summary: Create a project
|
||
description: >
|
||
When creating a project, the `id` property must not already exist in this Dougal installation.
|
||
|
||
Note that this endpoint accepts both JSON and YAML payloads.
|
||
|
||
**Security:**
|
||
|
||
* The user must have `edit` access on at least one organisation.
|
||
* The user will only be able to assign projects to organisations they have `edit` access to.
|
||
tags: [ "project", "configuration" ]
|
||
security:
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ProjectDefinition"
|
||
- required:
|
||
- id
|
||
- name
|
||
- epsg
|
||
- binning
|
||
application/yaml:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ProjectDefinition"
|
||
- required:
|
||
- id
|
||
- name
|
||
- epsg
|
||
- binning
|
||
responses:
|
||
"201":
|
||
description: The new project has been created
|
||
"400":
|
||
$ref: "#/components/responses/400"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"409":
|
||
description: The value used for the `id` property conflicts with an existing project.
|
||
|
||
/project/{project}/configuration:
|
||
get:
|
||
summary: Get a project's configuration
|
||
description: |
|
||
**Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.
|
||
|
||
**TODO:** Users with just `read` or `write` authorisation might need to get access to at least part of the configuration too.
|
||
tags: [ "project", "configuration" ]
|
||
security:
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/ETag"
|
||
- $ref: "#/components/parameters/CSVDelimiter"
|
||
responses:
|
||
"200":
|
||
description: Project configuration data.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
application/yaml:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
text/csv:
|
||
schema:
|
||
type: string
|
||
contentMediaType: text/csv
|
||
description: |
|
||
A CSV representation of the project configuration, with the following columns:
|
||
|
||
* `key`: Configuration value key.
|
||
* `value`: Configuration value entry.
|
||
|
||
The actual configuration object is ‘flattened’ by creating unique keys for nested values, consisting of the nested property names concatenated together with a `.` separator.
|
||
example: |
|
||
key,value
|
||
id,EQ23206
|
||
qc.parameters,/QC Defaults/parameters.yaml
|
||
qc.definitions,/QC Defaults/definitions.yaml
|
||
raw.ntbp.pattern.flags,i
|
||
raw.ntbp.pattern.regex,NTBP
|
||
raw.p111.globs.0,**/*.P111
|
||
raw.p111.globs.1,**/*.p111
|
||
raw.p111.paths.0,/Projects/2023/Grane EQ23206/01 Sequences Raw Files
|
||
raw.p111.pattern.flags,i
|
||
raw.p111.pattern.regex,^.*(10|20)([0-9]{4})([0-9])([0-9]{3})S00000\.([0-9]+)\.[Pp]?111$
|
||
raw.p111.pattern.captures.0,direction
|
||
raw.p111.pattern.captures.1,line
|
||
raw.p111.pattern.captures.2,attempt
|
||
raw.p111.pattern.captures.3,sequence
|
||
raw.p111.pattern.captures.4,file_no
|
||
|
||
|
||
put:
|
||
summary: Update a project's configuration.
|
||
description: >
|
||
The `id` property in the payload *must* match the `project` URL parameter.
|
||
|
||
**Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.
|
||
tags: [ "project", "configuration" ]
|
||
security:
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/If-Match"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ProjectDefinition"
|
||
- required:
|
||
- id
|
||
- name
|
||
- epsg
|
||
- binning
|
||
application/yaml:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ProjectDefinition"
|
||
- required:
|
||
- id
|
||
- name
|
||
- epsg
|
||
- binning
|
||
responses:
|
||
"200":
|
||
description: Project configuration data.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
application/yaml:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
"400":
|
||
description: There was a problem with the syntax or the data of the request
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
$ref: "#/components/responses/404"
|
||
"409":
|
||
description: The value used for the `id` property conflicts with an existing project.
|
||
"412":
|
||
$ref: "#/components/responses/412"
|
||
"428":
|
||
$ref: "#/components/responses/428"
|
||
|
||
patch:
|
||
summary: Partial project configuration update.
|
||
description: |
|
||
This endpoint is used to update part of a project configuration.
|
||
Partial representations may be provided, in which case, only the keys provided in the payload will be updated.
|
||
|
||
Keys referencing an object cause the payload to be merged into the existing object, arbitrarily deep. Other values (strings, arrays, numbers, etc.) are replaced instead.
|
||
|
||
If a key has a value of **null**, the key will be removed from the object.
|
||
|
||
**Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.
|
||
tags: [ "project", "configuration" ]
|
||
security:
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/If-Match"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
example:
|
||
{ "archived": true }
|
||
application/yaml:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
example: |
|
||
# Update the planner configuration details
|
||
# Recall that a complete representation of
|
||
# the `planner` object must be provided,
|
||
# even if only one of the values has changed.
|
||
planner:
|
||
defaultLineChangeDuration: 60 # One hour
|
||
defaultAcquisitionSpeed: 4.5 # Knots
|
||
overlapBefore: 16
|
||
overlapAfter: 16
|
||
|
||
responses:
|
||
"200":
|
||
description: >
|
||
A complete representation of the project configuration data, including
|
||
any changes applied by this request.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
application/yaml:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectDefinition"
|
||
"400":
|
||
description: There was a problem with the syntax or the data of the request
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
$ref: "#/components/responses/404"
|
||
"409":
|
||
description: The value used for the `id` property conflicts with an existing project.
|
||
"412":
|
||
$ref: "#/components/responses/412"
|
||
"428":
|
||
$ref: "#/components/responses/428"
|
||
|
||
|
||
|
||
/project/{project}:
|
||
# Synonym: /project/{project}/summary:
|
||
get:
|
||
summary: Get details about a specific project.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "project" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: Summary of project status and details.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProjectSummary"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/line/:
|
||
get:
|
||
summary: Get list of preplot lines.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "preplot" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of preplot lines.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PreplotLine"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/line/{line}:
|
||
patch:
|
||
summary: Update preplot line information.
|
||
description: |
|
||
All of the properties are optional. Users may specify only the one(s) they need, other properties remain unchanged. An empty object body causes the resource not to be modified at all.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "preplot" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Line"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
remarks:
|
||
type: string
|
||
description: Overwrite the remarks text
|
||
meta:
|
||
type: object
|
||
description: Overwrite the `meta` object with a new one.
|
||
ntba:
|
||
type: boolean
|
||
description: Set the ‘Not To Be Processed’ flag to `true` or `false`.
|
||
complete:
|
||
type: boolean
|
||
description: If `true`, set the ‘Not To Be Processed’ flag to `true` on any points in the line which have not yet been successfully acquired and processed at least once (virgin points). If `false`, set the NTBA flag to `false` on *all* points in this line.
|
||
|
||
responses:
|
||
"204":
|
||
description: The resource has been successfully updated.
|
||
|
||
|
||
/project/{project}/sequence/:
|
||
get:
|
||
summary: Get list of sequences.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "sequences" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of sequences.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Sequence"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/sequence/{sequence}:
|
||
get:
|
||
summary: Get a sequence
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "sequences" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Sequence"
|
||
responses:
|
||
"200":
|
||
description: Sequence data.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Sequence"
|
||
application/vnd.seis+json:
|
||
schema:
|
||
type: object
|
||
application/geo+json:
|
||
schema:
|
||
$ref: "#/components/schemas/GeoJSONFeature"
|
||
text/html:
|
||
schema:
|
||
type: string
|
||
application/pdf:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
patch:
|
||
summary: Update sequence information.
|
||
description: |
|
||
All of the properties are optional. Users may specify only the one(s) they need, other properties remain unchanged. An empty object body causes the resource not to be modified at all. Final sequence properties only have effect if a final P1 file exists for the relevant sequence.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
|
||
tags: [ "sequences" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Sequence"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
remarks:
|
||
type: string
|
||
description: Overwrite the remarks text for the raw sequence
|
||
remarks_final:
|
||
type: string
|
||
description: Overwrite the remarks text for the final sequence, if it exists
|
||
meta:
|
||
description: Overwrite the `meta` object for the raw sequence
|
||
type: object
|
||
meta_final:
|
||
type: object
|
||
description: Overwrite the `meta` object for the final sequence, if it exists
|
||
responses:
|
||
"204":
|
||
description: The resource has been successfully updated.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/sequence/{sequence}/{shot}:
|
||
get:
|
||
summary: Retrieve shotpoint information
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "sequences" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Sequence"
|
||
- $ref: "#/components/parameters/Shotpoint"
|
||
- $ref: "#/components/parameters/QueryProject"
|
||
-
|
||
description: Source of shotpoint data.
|
||
name: kind
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [ raw, final ]
|
||
default: raw
|
||
responses:
|
||
"200":
|
||
description: Shotpoint data
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Shotpoint"
|
||
application/geo+json:
|
||
schema:
|
||
$ref: "#/components/schemas/GeoJSONFeature"
|
||
"404":
|
||
description: |
|
||
The requested shotpoint does not exist.
|
||
|
||
If used with `kind=final`, a **404** will be returned if the sequence has not yet been processed.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/plan:
|
||
get:
|
||
summary: Get list of planned sequences.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "planner" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of planned sequences.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
remarks:
|
||
type: string
|
||
description: Planner remarks
|
||
sequences:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
text/csv:
|
||
schema:
|
||
type: string
|
||
format: csv
|
||
description: |
|
||
Returns a CSV response containing one row for each planned sequence, with the following columns:
|
||
|
||
* `sequence`: Sequence number
|
||
* `line`: Line number
|
||
* `fsp`: First shotpoint
|
||
* `lsp`: Last shotpoint
|
||
* `ts0`: Estimated timestamp of the first shotpoint
|
||
* `ts1`: Estimated timestamp of the last shotpoint
|
||
* `name`: Line name
|
||
* `remarks`: Arbitrary comments
|
||
* `num_points`: Number of shotpoints
|
||
* `duration`: Estimated duration in seconds
|
||
* `length`: Line length in metres
|
||
* `azimuth`: Line azimuth
|
||
* `lon0`: Longitude of the first shotpoint
|
||
* `lat0`: Latitude of the first shotpoint
|
||
* `lon1` Longitude of the last shotpoint
|
||
* `lat1`: Latitude of the last shotpoint
|
||
example: |
|
||
"sequence","line","fsp","lsp","ts0","ts1","name","remarks","num_points","duration","length","azimuth","lon0","lat0","lon1","lat1"
|
||
81,5162,2422,1158,"2023-10-22T11:09:24.912Z","2023-10-22T12:56:03.395Z","2051621081S00000","",633,6398,15799.988472147348,26.4703415983101,2.474872,59.086695,2.596266,59.214146
|
||
82,5178,2444,1146,"2023-10-22T12:56:03.000Z","2023-10-22T14:45:33.607Z","2051781082S00000","",650,6570,16225.02094944685,26.470137885560813,2.469632,59.085264,2.594277,59.216147
|
||
text/html:
|
||
schema:
|
||
type: string
|
||
format: html
|
||
description: |
|
||
An HTML representation of the plan.
|
||
application/pdf:
|
||
schema:
|
||
type: string
|
||
contentMediaType: application/pdf
|
||
description: |
|
||
A PDF representation of the plan.
|
||
|
||
|
||
post:
|
||
summary: Add a new sequence to the plan.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
responses:
|
||
"201":
|
||
description: Sequence successfully added
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
put:
|
||
summary: Modify a planned sequence
|
||
description: |
|
||
Note that the `line` property cannot be modified and if supplied it will be silently ignored. To change the line, delete the sequence and create a new one. To change the sequence number, use a `PATCH` request instead.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
responses:
|
||
"201":
|
||
description: Sequence successfully modified
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/plan/{sequence}:
|
||
patch:
|
||
summary: Modify a planned sequence
|
||
description: |
|
||
By using this endpoint it is possible to change the sequence number by providing the new value in the `sequence` property of the request body. On the other hand, the `line` property cannot be modified.
|
||
|
||
Note that only those attributes that are to be modified are required to be supplied in the request body.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Sequence"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
responses:
|
||
"201":
|
||
description: Sequence successfully modified
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
delete:
|
||
summary: Remove a sequence from the plan.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Sequence"
|
||
responses:
|
||
"204":
|
||
description: Returned when the sequence no longer exists in the plan. Note that it is possible that the sequence never existed in the first place, as supplying a valid but non-existing sequence number is not an error.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
# /project/{project}/linename:
|
||
# post:
|
||
# summary: Get a line name based on the supplied data
|
||
# tags: [ "planner" ]
|
||
# security:
|
||
# - BearerAuthGuest: []
|
||
# - CookieAuthGuest: []
|
||
# requestBody:
|
||
# required: true
|
||
# content:
|
||
# application/json:
|
||
# schema:
|
||
#
|
||
# responses:
|
||
# "200":
|
||
# description: Available line name items
|
||
# content:
|
||
# application/json:
|
||
# schema:
|
||
# $ref: "#/components/schemas/LineNameProperties"
|
||
|
||
|
||
|
||
/project/{project}/linename/properties:
|
||
get:
|
||
summary: Get available line name components
|
||
description: |
|
||
This endpoint returns a description of the available items that
|
||
may be used to construct a line name, such as line number, sequence,
|
||
etc.
|
||
|
||
**Security:** As this endpoint is only ever called by those editing the configuration,
|
||
`edit` authorisation on at least one organisation can be required. Alternatively, it
|
||
can just be left open to everyone. (TODO)
|
||
tags: [ "planner" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
responses:
|
||
"200":
|
||
description: Available line name items
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/LineNameProperties"
|
||
|
||
/project/{project}/event:
|
||
get:
|
||
summary: Get project events.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/CSVDelimiter"
|
||
- $ref: "#/components/parameters/CSVFields"
|
||
- $ref: "#/components/parameters/CSVHeader"
|
||
- $ref: "#/components/parameters/QueryMime"
|
||
- $ref: "#/components/parameters/QueryFilename"
|
||
responses:
|
||
"200":
|
||
description: List of project events
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Event"
|
||
|
||
application/geo+json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GeoJSONFeature"
|
||
|
||
application/vnd.seis+json:
|
||
schema:
|
||
$ref: "#/components/schemas/SeisExport"
|
||
|
||
application/yaml:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Event"
|
||
example: |
|
||
- id: 12042
|
||
tstamp: 2023-10-15T12:43:16.000Z
|
||
sequence: null
|
||
point: null
|
||
remarks: New event 5
|
||
labels: []
|
||
meta: {}
|
||
has_edits: true
|
||
modified_on: 2023-10-17T08:51:51.069Z
|
||
- id: 11727
|
||
tstamp: 2023-10-05T06:02:54.664Z
|
||
sequence: 80
|
||
point: 2364
|
||
remarks: LGSP 2051220080S00000
|
||
labels:
|
||
- LGSP
|
||
meta:
|
||
auto:
|
||
LGSP: final_line
|
||
has_edits: false
|
||
modified_on: 2023-10-14T19:50:08.429Z
|
||
- id: 11728
|
||
tstamp: 2023-10-05T06:02:54.664Z
|
||
sequence: 80
|
||
point: 2364
|
||
remarks: LSP 2051220080S00000
|
||
labels:
|
||
- LSP
|
||
meta:
|
||
auto:
|
||
LSP: final_line
|
||
has_edits: false
|
||
modified_on: 2023-10-14T19:50:08.429Z
|
||
|
||
|
||
text/csv:
|
||
schema:
|
||
type: string
|
||
contentMediaType: text/csv
|
||
description: |
|
||
A CSV representation of the event log, with the following columns:
|
||
|
||
* `timestamp`: Event timestamp, in UTC.
|
||
* `sequence`: Sequence number, if applicable.
|
||
* `point`: Point number, if applicable.
|
||
* `text`: Event text. May contain newlines and [Markdown](https://daringfireball.net/projects/markdown/syntax "Markdown syntax"). formatting.
|
||
* `labels`: Labels associated with the event. Multiple labels are separated by `;` *(be careful about using `;` as a field separator!)*
|
||
* `latitude`: Event latitude, if the event has a Point geometry.
|
||
* `longitude`: Event longitude, if the event has a Point geometry.
|
||
* `id`: Event ID internal to Dougal.
|
||
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
post:
|
||
summary: Add a new event
|
||
description: |
|
||
Creates a new event in the database.
|
||
|
||
Either `tstamp` or *both of* `sequence` and `point` must be present. It is also acceptable to provide all three, but the system *will not check for consistency.*
|
||
|
||
If `tstamp` is missing the system will try to populate it from the shots table, but that may not happen immediately.
|
||
|
||
It is possible to add an event for a sequence or shot which does not (yet) exist. If the shot eventually comes into existence the timestamp will be populated accordingly.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EventNew"
|
||
responses:
|
||
"201":
|
||
description: New event created successfully
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
/project/{project}/event/{id}:
|
||
get:
|
||
summary: Retrieve event history.
|
||
description: |
|
||
Get all the history for an event.
|
||
|
||
When an event is modified, a new instance is created and saved in the database along with the modification timestamps. Similarly, when an event is deleted its latest instance is merely marked with an end of validity time, causing it to no longer appear in the event lists.
|
||
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/EventID"
|
||
responses:
|
||
"200":
|
||
description: Event history
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/EventUniqueEdit"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
put:
|
||
summary: Update an existing event.
|
||
description: |
|
||
All of the attributes must be present even if they haven't been modified, otherwise the request will fail or the attributes will take their default values, which is likely not what you want.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/EventID"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EventNew"
|
||
responses:
|
||
"201":
|
||
description: Event updated successfully.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
patch:
|
||
summary: Patch an event.
|
||
description: |
|
||
Unlike the `PUT` verb, a `PATCH` does not require all attributes to be provided, but only those that have actually been modified, plus `id`.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/EventID"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EventNew"
|
||
responses:
|
||
"201":
|
||
description: Event updated successfully.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
delete:
|
||
summary: Delete an event.
|
||
description: |
|
||
Does not actually delete the event but marks it as no longer valid in the database.
|
||
|
||
There is no explicit mechanism to *undelete* an event, but its history can be retrieved via the relevant endpoint and the the last (or any other) instance `PUT` back in, which will cause the event to be undeleted while leaving a record of its previous deletion.
|
||
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/EventID"
|
||
responses:
|
||
"204":
|
||
description: The event no longer exists.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/changes/{since}:
|
||
get:
|
||
summary: Get event change history since epoch.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/Since"
|
||
- $ref: "#/components/parameters/Unique"
|
||
responses:
|
||
"200":
|
||
description: List of project event changes. If `unique` is given, only the latest version of each event will be returned, otherwise the entire modification history is given, potentially including the same event `id` multiple times.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/EventChanges"
|
||
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/label:
|
||
get:
|
||
summary: Get project labels.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "project" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of project label definitions
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/qc/results:
|
||
get:
|
||
summary: Get QC results.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: Project QC results.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
description: |
|
||
The returned object is a tree structure of QC tests and their results.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
delete:
|
||
summary: Delete all QC results.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- BearerAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"204":
|
||
description: |
|
||
All QC results for the project have been deleted.
|
||
Note that unless the project has been archived, the QCs will be regenerated in the next run of the deferred tasks process.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/qc/results/accept:
|
||
post:
|
||
summary: Accept shotpoint QC results.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- BearerAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: integer
|
||
description: Event ID of the QC result to mark as accepted.
|
||
responses:
|
||
"204":
|
||
description: |
|
||
The QC events referenced in the request body have been marked as accepted. These events will not be exported to Seis+JSON files or derived human-readable reports.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
/project/{project}/qc/results/unaccept:
|
||
post:
|
||
summary: Unaccept shotpoint QC results.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- BearerAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"204":
|
||
description: |
|
||
The QC events referenced in the request body are no longer marked as accepted.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: integer
|
||
description: Event ID of the QC result to no longer mark accepted.
|
||
|
||
|
||
/project/{project}/qc/results/sequence/{sequence}:
|
||
get:
|
||
summary: Get sequence QC results.
|
||
description: |
|
||
**Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/SequenceNumber"
|
||
responses:
|
||
"200":
|
||
description: Sequence QC results.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
description: |
|
||
The returned object is a tree structure of QC tests and their results for a specific sequence
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
delete:
|
||
summary: Delete sequence QC results.
|
||
description: |
|
||
**Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
|
||
tags: [ "qc" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- BearerAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
- $ref: "#/components/parameters/SequenceNumber"
|
||
responses:
|
||
"204":
|
||
description: |
|
||
All QC results for the sequence have been deleted.
|
||
Note that unless the project has been archived, the QCs will be regenerated in the next run of the deferred tasks process.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/configuration/{path}:
|
||
get:
|
||
summary: Get project configuration data.
|
||
tags: [ "project" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
-
|
||
description: Path to configuration object. Nested objects are denoted by `/`.
|
||
name: path
|
||
in: path
|
||
schema:
|
||
type: string
|
||
example: /online/line/pattern
|
||
responses:
|
||
"200":
|
||
description: Parameter value
|
||
content:
|
||
application/json:
|
||
schema:
|
||
anyOf:
|
||
- type: object
|
||
- type: array
|
||
- type: string
|
||
- type: number
|
||
- type: boolean
|
||
example:
|
||
{
|
||
"flags": "i",
|
||
"regex": "^.*(10|20)([0-9]{4})([0-9])([0-9]{3})S00000$",
|
||
"captures": [
|
||
"direction",
|
||
"line",
|
||
"attempt",
|
||
"sequence"
|
||
]
|
||
}
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
description: The requested parameter does not exist. Note that the HTTP return code allows us to differentiate between a non-existent parameter and one which is `null` or `undefined`.
|
||
|
||
|
||
|
||
/project/{project}/info/{path}:
|
||
get:
|
||
summary: Get project information data.
|
||
description: Each project has a key/value store where arbitrary information can be stored. The keys are simple strings and the values are JSON objects. This endpoint allows access to this information; either the full object can be returned or a subset of it, by setting the `{path}` accordingly.
|
||
tags: [ "project" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
-
|
||
description: Item key, optionally followed by an object path, all `/` separated.
|
||
name: path
|
||
in: path
|
||
schema:
|
||
type: string
|
||
required: true
|
||
example: /qc
|
||
responses:
|
||
"200":
|
||
description: Parameter value, if found. Note that unlike the project configuration endpoint, a non-existent key or non-existent object path still results in a valid response, albeit with an empty body. Clients should be prepared for this.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
anyOf:
|
||
- type: object
|
||
- type: array
|
||
- type: string
|
||
- type: number
|
||
- type: boolean
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/meta/{type}/{kind}/{path}:
|
||
get:
|
||
summary: Get metadata
|
||
description: |
|
||
Retrieve metadata from project elements. The valid `{type}` and `{kind}` combinations are as follows:
|
||
|
||
Type/Kind | `preplot` | `raw` | `final`
|
||
------------|-----------|-------|---------
|
||
`sequences` | ✘ | ✔ | ✔
|
||
`points` | ✘ | ✔ | ✔
|
||
`lines` | ✔ | ✘ | ✘
|
||
|
||
tags: [ "project", "metadata" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
-
|
||
description: Element type.
|
||
name: type
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- sequences
|
||
- points
|
||
- lines
|
||
-
|
||
description: Element kind.
|
||
name: kind
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- raw
|
||
- final
|
||
- preplot
|
||
-
|
||
description: Object path.
|
||
name: path
|
||
in: path
|
||
schema:
|
||
type: string
|
||
responses:
|
||
"200":
|
||
description: Metadata
|
||
content:
|
||
application/json:
|
||
schema:
|
||
anyOf:
|
||
- type: object
|
||
- type: array
|
||
- type: string
|
||
- type: number
|
||
- type: boolean
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
description: The requested data does not exist. Note that the HTTP return code allows us to differentiate between a non-existent item and one which is `null` or `undefined`.
|
||
|
||
|
||
/project/{project}/meta:
|
||
put:
|
||
summary: Update metadata.
|
||
tags: [ "project", "metadata" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
type:
|
||
type: string
|
||
enum:
|
||
- raw
|
||
- final
|
||
- preplot
|
||
default: raw
|
||
sequence:
|
||
type: integer
|
||
description: "If `point` is not present or `null`: sequence to be updated; else, the `sequence` / `point` pair is used to select the point the metadata of which is to be updated."
|
||
line:
|
||
type: integer
|
||
description: Always used along with `point` to update a specific preplot point. If both `sequence` and `line` are present, `sequence` takes precedence. If `line` is present, the `type` parameter is ignored.
|
||
point:
|
||
type: integer
|
||
description: Used together with `sequence` or `line` to update a raw or final shot, or a preplot point, respectively.
|
||
path:
|
||
type: string
|
||
description: A `/` separated path into the metadata object to update only a specific attribute while keeping the rest of the metadata intact. If not present, the entire metadata object will be overwritten.
|
||
value:
|
||
type: object
|
||
description: The value to be assigned to the metadata attribute (if `path` is present) or to the metadata object itself. It can be any JSON primitive.
|
||
responses:
|
||
"201":
|
||
description: Metadata updated successfully.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
/files/{path}:
|
||
get:
|
||
summary: Download files or list directories
|
||
description: |
|
||
* If `{path}` refers to a file, this endpoint will return the file contents with a [`200`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) response code.
|
||
* If `{path}` refers to a directory, this endpoint will return a listing of the directory's immediate children
|
||
with a [`203`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/203) response code, to differentiate this case from the case where an actual JSON file is being downloaded.
|
||
* If `{path}` does not exist or is not accessible, this endpoint responds with a [`404`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404).
|
||
|
||
For file downloads, the server will try to guess the correct MIME type and will set [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) accordingly,
|
||
defaulting to `application/octet-stream` if a more precise type cannot be determined. Pay attention to the [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) header, if present, as responses *may* be compressed, in the presence of a suitable [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header in the request.
|
||
tags: [ "files" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/FilePath"
|
||
responses:
|
||
"200":
|
||
description: File contents.
|
||
content:
|
||
"*/*":
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
"203":
|
||
description: Directory listing.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
path:
|
||
type: string
|
||
description: Full path on the server.
|
||
basename:
|
||
type: string
|
||
description: File name, including any extension, or directory name.
|
||
"Content-Type":
|
||
type: string
|
||
description: MIME type, defaulting to `application/octet-stream` if a more precise type cannot be determined and the entry refers to a regular file (symbolic links are always resolved), or `inode/directory` if the entry is a directory.
|
||
size:
|
||
type: integer
|
||
description: |
|
||
The size of the file in bytes.
|
||
|
||
If the underlying file system does not support getting the size of the file, this will be 0.
|
||
atime:
|
||
type: number
|
||
description: The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch.
|
||
mtime:
|
||
type: number
|
||
description: The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch.
|
||
ctime:
|
||
type: number
|
||
description: The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch.
|
||
birthtime:
|
||
type: number
|
||
description: The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
$ref: "#/components/responses/404"
|
||
|
||
|
||
/navdata:
|
||
get:
|
||
summary: Get navigation data.
|
||
tags: [ "navdata" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/QueryLimit"
|
||
- $ref: "#/components/parameters/QueryOffset"
|
||
-
|
||
description: |
|
||
Select only the values matching this query.
|
||
|
||
Recognised parameters are:
|
||
|
||
* `tstamp`, `tolerance`: temporal restriction to *tstamp ±tolerance*.
|
||
* `pos`, `radius`: geographic restriction to data within *radius* metres of *pos*.
|
||
|
||
Units and formats:
|
||
|
||
* `tstamp`: An ISO-8601 timestamp.
|
||
* `tolerance`: A value in milliseconds.
|
||
* `pos`: Given as longitude, latitude (λ,φ)
|
||
* `radius`: A value in metres.
|
||
|
||
Default values:
|
||
|
||
* `tolerance`: 1000 ms
|
||
* `radius`: 1 m
|
||
name: q
|
||
in: query
|
||
schema:
|
||
type: string
|
||
example: "tstamp:2021-10-08T10:37:57Z;tolerance:5000;pos:2.479345,59.182838;radius:115"
|
||
-
|
||
# FIXME Replace this parameter with $ref: "#/components/parameters/QueryProject"
|
||
description: Subset of attributes to be returned
|
||
name: fields
|
||
in: query
|
||
schema:
|
||
type: string
|
||
pattern: "(([^\\s,;:]+)(\\s*[,;\\s]\\s*)?)+"
|
||
|
||
responses:
|
||
"200":
|
||
description: List of navigation data items
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/NavData"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/navdata/gis/point:
|
||
get:
|
||
summary: Get navigation data as GeoJSON point features
|
||
tags: [ "navdata" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/QueryLimit"
|
||
- $ref: "#/components/parameters/QueryOffset"
|
||
responses:
|
||
"200":
|
||
description: List of GeoJSON point features
|
||
content:
|
||
application/geo+json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GeoJSONFeature"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/navdata/gis/line:
|
||
get:
|
||
summary: Get navigation data as GeoJSON line features
|
||
tags: [ "navdata" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
-
|
||
description: Maximum number of line vertices
|
||
name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 2
|
||
- $ref: "#/components/parameters/QueryOffset"
|
||
responses:
|
||
"200":
|
||
description: GeoJSON line feature
|
||
content:
|
||
application/geo+json:
|
||
schema:
|
||
$ref: "#/components/schemas/GeoJSONFeature"
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/queue/outgoing/asaqc:
|
||
get:
|
||
summary: Get list of queued items.
|
||
tags: [ "asaqc" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
parameters:
|
||
-
|
||
name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [ "queued", "cancelled", "failed", "sent" ]
|
||
description: Return only items with matching status. If unspecified, items will not be filtered by status.
|
||
-
|
||
name: order
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- created_on
|
||
- updated_on
|
||
- not_before
|
||
- item_id
|
||
- status
|
||
- parent_id
|
||
- project
|
||
- sequence
|
||
default: updated_on
|
||
description: Order the returned items by the specified property.
|
||
-
|
||
name: dir
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [ '-', '+' ]
|
||
default: '-'
|
||
description: |
|
||
Specify whether to order items in ascending or descending order.
|
||
|
||
* `-` indicates descending order.
|
||
* `+` indicates ascending order (in fact, *anything at all* other than `-` means ascending order).
|
||
-
|
||
name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 1000
|
||
description: Maximum number of items to retrieve.
|
||
- $ref: "#/components/parameters/QueryOffset"
|
||
responses:
|
||
"200":
|
||
description: List of queue items
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/QueueItem"
|
||
example:
|
||
[
|
||
{
|
||
"item_id": 167,
|
||
"status": "sent",
|
||
"payload": {
|
||
"project": "eq21203",
|
||
"sequence": 176
|
||
},
|
||
"results": [
|
||
{
|
||
"digest": {
|
||
"sha256": {
|
||
"hex": "b67e3a925e0b0845a6e6cfd386acb7841a781b19b994295e251caa635b7c0753"
|
||
}
|
||
},
|
||
"response": {
|
||
"id": "118d5a69-a235-4306-887c-90a5fd178e79",
|
||
"fileName": "2053721176S00000-NavLog-1.json"
|
||
}
|
||
},
|
||
{
|
||
"digest": {
|
||
"sha256": {
|
||
"hex": "9ea30986db8d44400a3352767a8d4cf794ee68b96c793e0e12fba82363d2f5b1"
|
||
}
|
||
},
|
||
"response": {
|
||
"id": "300d291b-7355-44eb-a15a-5ba5637dac65",
|
||
"fileName": "2053721176S00000-NavLog-1.pdf"
|
||
}
|
||
}
|
||
],
|
||
"created_on": "2021-10-03T18:32:25.480Z",
|
||
"updated_on": "2021-10-03T18:35:10.632Z",
|
||
"not_before": "1970-01-01T00:00:00.000Z",
|
||
"parent_id": 166
|
||
},
|
||
{
|
||
"item_id": 166,
|
||
"status": "failed",
|
||
"payload": {
|
||
"project": "eq21203",
|
||
"sequence": 176
|
||
},
|
||
"results": [
|
||
{
|
||
"digest": {
|
||
"sha256": {
|
||
"hex": "2fbacfc0414a51d07629c35efa7d29c5012461d16ddcccb89804d1522c10b553"
|
||
}
|
||
},
|
||
"response": {
|
||
"error": {}
|
||
}
|
||
},
|
||
{
|
||
"digest": {
|
||
"sha256": {
|
||
"hex": "4910443e3be2c34990783bb7968746f62dd4ae1fea1c5499ce81f5ba2f262e68"
|
||
}
|
||
},
|
||
"response": {
|
||
"error": {
|
||
"code": "ECONNREFUSED",
|
||
"type": "system",
|
||
"errno": "ECONNREFUSED",
|
||
"message": "request to https://localhost:3077/vt/v1/api/upload-file-encoded failed, reason: connect ECONNREFUSED 127.0.0.1:3077"
|
||
}
|
||
}
|
||
}
|
||
],
|
||
"created_on": "2021-10-03T18:32:05.585Z",
|
||
"updated_on": "2021-10-03T18:32:25.392Z",
|
||
"not_before": "1970-01-01T00:00:00.000Z",
|
||
"parent_id": null
|
||
}
|
||
]
|
||
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
post:
|
||
summary: Add one or more items to the queue.
|
||
tags: [ "asaqc" ]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/QueueRequestASAQC"
|
||
responses:
|
||
"202":
|
||
description: |
|
||
All items were added to the queue for processing.
|
||
|
||
Note that this response does not imply that items have been sent or will be delivered, or that an entity matching the request even exists. It is merely a promise to attempt a transfer at some later time, if the item exists and the remote server is reachable.
|
||
"400":
|
||
description: |
|
||
The request was malformed or had invalid data.
|
||
|
||
If a request consisting of multiple items fails, none of the items get added to the queue.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
/queue/outgoing/asaqc/{id}:
|
||
delete:
|
||
summary: Cancel a queued transfer.
|
||
description: Use this request to cancel a queued transfer before it is sent. This endpoint does not return a body, success or failure is denoted by the HTTP response status code.
|
||
tags: [ "asaqc" ]
|
||
parameters:
|
||
-
|
||
name: id
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
description: The ID of a queued request.
|
||
responses:
|
||
"204":
|
||
description: |
|
||
Request successfully cancelled. No data has been sent or will be sent.
|
||
|
||
* If the referenced request had status `queued`, its status was changed to `cancelled`.
|
||
* If the referenced request had status `failed` and there existed one or more requests with status `queued` and `parent_id` equal to this request's ID, their status was changed to `cancelled`.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
"404":
|
||
description: The request does not exist or it has already been fulfilled and cannot therefore be cancelled.
|
||
|
||
|
||
/version:
|
||
get:
|
||
summary: Get version information
|
||
tags: [ "misc" ]
|
||
security: null
|
||
responses:
|
||
"200":
|
||
description: Version data
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/SoftwareVersion"
|
||
|
||
|
||
/diagnostics:
|
||
get:
|
||
summary: Get server diagnostics
|
||
description: This endpoint returns server information useful for diagnostics and monitoring.
|
||
tags: [ "misc" ]
|
||
security: null
|
||
responses:
|
||
"200":
|
||
description: Diagnostics data
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ServerDiagnostics"
|
||
|
||
|
||
/user:
|
||
get:
|
||
summary: Get list of users
|
||
description: |
|
||
Returns a list of users belonging to the organisation(s) that the requesting
|
||
user has `write` or `edit` access to.
|
||
tags: [ "users" ]
|
||
security:
|
||
- BearerAuthAdmin: []
|
||
- CookieAuthAdmin: []
|
||
responses:
|
||
"200":
|
||
description: |
|
||
List of users
|
||
|
||
* If the requesting user has only `write` access to the organisation, a limited subset of details (`SimpleUser`) will be returned
|
||
* If the requesting user has `edit` access, a full `User` entity will be returned
|
||
* For a requesting user that belongs to multiple organisations with different access levels, a mix of `SimpleUser` and `User` entities may be returned.
|
||
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
anyOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- $ref: "#/components/schemas/User"
|
||
|
||
post:
|
||
summary: Create a user
|
||
description: |
|
||
Via this endpoint, an existing user can create new users on organisations for which he has `edit` access.
|
||
tags: [ "users" ]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
responses:
|
||
"200":
|
||
description: |
|
||
New user details
|
||
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
|
||
|
||
/user/{id}:
|
||
|
||
get:
|
||
summary: Get user details
|
||
tags: [ "users" ]
|
||
responses:
|
||
"200":
|
||
description: |
|
||
User details
|
||
|
||
* If the requesting user has only `write` access to the organisation(s) of the requested user, a limited subset of details (`SimpleUser`) will be returned
|
||
* If the requesting user has `edit` access to any of the organisations of the requested user, a full `User` entity will be returned
|
||
* If the requesting and the requested users are the same, a full `User` entity will be returned (this reveals the login method used)
|
||
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/SimpleUser"
|
||
- $ref: "#/components/schemas/User"
|
||
|
||
put:
|
||
summary: Edit a user
|
||
description: |
|
||
A user can be edited either by himself (`NamedUser` only) or by someone with `edit`
|
||
access to at least one of the user's organisations.
|
||
|
||
In the case of a `NamedUser` self edit, only certain properties may be modified.
|
||
tags: [ "users" ]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
-
|
||
$ref: "#/components/schemas/User"
|
||
-
|
||
$ref: "#/components/schemas/NamedUserSelfEditable"
|
||
responses:
|
||
"200":
|
||
description: |
|
||
New user details
|
||
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
|
||
delete:
|
||
summary: Delete a user
|
||
description: |
|
||
**Deleting a user is an irreversible action. Use with care!**
|
||
tags: [ "users" ]
|
||
responses:
|
||
"204":
|
||
description: |
|
||
The user has been deleted
|
||
"404":
|
||
description: |
|
||
The target user does not exist or the requesting user does not
|
||
have sufficient rights over it
|
||
|
||
/user/validate/{validation_id}:
|
||
get:
|
||
summary: Request user validation
|
||
tags: [ "users" ]
|
||
responses:
|
||
"200":
|
||
description: |
|
||
When a user identified by a user name and password is created and an email address is provided, the new user receives an email with a link to this endpoint. In this endpoint, the user will acknowledge that he wants to proceed with registration and enter a password.
|
||
|
||
This endpoint is also used when the email address of an existing user is changed, to validate the new address. In this case, no password prompt is issued.
|
||
|
||
Finally, this endpoint can be used in case the user forgets his password, to enter a new one.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/UserValidationRequest"
|
||
|
||
post:
|
||
summary: Confirm user validation request
|
||
tags: [ "users" ]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/UserValidationResponse"
|
||
responses:
|
||
"204":
|
||
summary: Validation successful
|
||
description: |
|
||
The server has accepted and processed the validation response.
|
||
"404":
|
||
summary: Not found
|
||
description: |
|
||
No validation request exists with this `id`. It may have never existed or it may have already expired.
|
||
|
||
|
||
|
||
|
||
/login:
|
||
post:
|
||
summary: Request a user token.
|
||
description: Users are identified by a username and a password. Usernames do not need to be unique, meaning that the same username can have different passwords and each user/password combination can have its own role. For instance, a user could have one password for everyday use and another to log in as administrator.
|
||
tags: [ "login" ]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
user:
|
||
type: string
|
||
description: User name to log in as
|
||
password:
|
||
type: string
|
||
description: Password corresponding to given user and requested role
|
||
responses:
|
||
"204":
|
||
description: Login successful. The token is returned in a `Set-Cookie` header.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/logout:
|
||
get:
|
||
summary: Log out (GET alternative).
|
||
description: |
|
||
Visiting this endpoint will cause the authorisation cookie `JWT` to be overwritten with an expired cookie, hopefully causing user agents to forget the previous token.
|
||
|
||
Note that this does not necessarily mean that the user *will* be logged out. The only way to truly log out, other than removing the user from the system, is for the client to forget its token or let it expire.
|
||
|
||
Note that the user may be logged back in automatically on the next API request if they are connecting from an authorised network or host.
|
||
|
||
tags: [ "login" ]
|
||
post:
|
||
summary: Log out (POST alternative).
|
||
description: Same as its `GET` counterpart. It does not require a body and if one is sent it will be ignored.
|
||
tags: [ "login" ]
|