mirror of
https://gitlab.com/wgp/dougal/software.git
synced 2025-12-06 13:27:08 +00:00
1366 lines
55 KiB
YAML
1366 lines
55 KiB
YAML
openapi: 3.0.0
|
||
info:
|
||
version: 0.1.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://siddis.dougal.aaltronav.eu/api
|
||
description: M/V Siddis Sailor, external access
|
||
- url: https://lan.siddis.dougal.aaltronav.eu/api
|
||
description: M/V Siddis Sailor, 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: metadata
|
||
description: Project items metadata
|
||
-
|
||
name: navdata
|
||
description: Data from navigation headers
|
||
|
||
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.
|
||
|
||
responses:
|
||
401Error:
|
||
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
|
||
|
||
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
|
||
|
||
Sequence:
|
||
description: Sequence number
|
||
name: sequence
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 115
|
||
|
||
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
|
||
|
||
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."
|
||
|
||
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.
|
||
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.
|
||
|
||
|
||
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.
|
||
|
||
Event:
|
||
type: object
|
||
properties:
|
||
type:
|
||
type: string
|
||
enum:
|
||
- timed
|
||
- sequence
|
||
- midnight shot
|
||
- qc
|
||
virtual:
|
||
type: boolean
|
||
sequence:
|
||
type: integer
|
||
nullable: true
|
||
point:
|
||
type: integer
|
||
nullable: true
|
||
id:
|
||
type: integer
|
||
remarks:
|
||
type: string
|
||
line:
|
||
type: integer
|
||
nullable: true
|
||
objref:
|
||
type: integer
|
||
nullable: true
|
||
tstamp:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
hash:
|
||
type: string
|
||
nullable: true
|
||
geometry:
|
||
$ref: "#/components/schemas/GeoJSONPoint"
|
||
labels:
|
||
type: array
|
||
items:
|
||
type: string
|
||
|
||
|
||
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`)
|
||
|
||
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
|
||
paths:
|
||
|
||
/project:
|
||
get:
|
||
description: Get list of projects.
|
||
tags: [ "project" ]
|
||
responses:
|
||
"200":
|
||
description: List of projects
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
pid:
|
||
type: string
|
||
name:
|
||
type: string
|
||
schema:
|
||
type: string
|
||
meta:
|
||
type: object
|
||
"401":
|
||
$ref: "#/components/responses/401Error"
|
||
|
||
/project/{project}:
|
||
# Synonym: /project/{project}/summary:
|
||
get:
|
||
description: Get details about a specific project.
|
||
tags: [ "project" ]
|
||
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/401Error"
|
||
|
||
|
||
/project/{project}/line/:
|
||
get:
|
||
description: Get list of preplot lines.
|
||
tags: [ "preplot" ]
|
||
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/401Error"
|
||
|
||
|
||
/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.
|
||
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`.
|
||
|
||
responses:
|
||
"204":
|
||
description: The resource has been successfully updated.
|
||
|
||
|
||
/project/{project}/sequence/:
|
||
get:
|
||
description: Get list of sequences.
|
||
tags: [ "sequences" ]
|
||
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/401Error"
|
||
|
||
|
||
/project/{project}/sequence/{sequence}:
|
||
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.
|
||
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.
|
||
|
||
|
||
/project/{project}/plan:
|
||
get:
|
||
description: Get list of planned sequences.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of planned sequences.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
|
||
post:
|
||
description: Add a new sequence to the plan.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
responses:
|
||
"201":
|
||
description: Sequence successfully added
|
||
|
||
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.
|
||
tags: [ "planner" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PlannedSequence"
|
||
responses:
|
||
"201":
|
||
description: Sequence successfully modified
|
||
|
||
|
||
/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.
|
||
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
|
||
|
||
delete:
|
||
description: Remove a sequence from the plan.
|
||
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.
|
||
|
||
|
||
/project/{project}/event:
|
||
get:
|
||
summary: Get project events.
|
||
tags: [ "log" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
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"
|
||
post:
|
||
summary: Add a new event
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Event"
|
||
responses:
|
||
"201":
|
||
description: New event created successfully
|
||
put:
|
||
summary: Update an existing event.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Event"
|
||
responses:
|
||
"201":
|
||
description: Event updated successfully.
|
||
delete:
|
||
summary: Delete an event.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
type:
|
||
type: string
|
||
enum:
|
||
- timed
|
||
- sequence
|
||
id:
|
||
type: integer
|
||
responses:
|
||
"204":
|
||
description: The event no longer exists.
|
||
|
||
|
||
/project/{project}/event/{type}/{id}:
|
||
put:
|
||
summary: Update an existing event.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
-
|
||
description: Event type
|
||
name: type
|
||
in: path
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- timed
|
||
- sequence
|
||
required: true
|
||
-
|
||
description: Event ID
|
||
name: id
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 1
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Event"
|
||
responses:
|
||
"201":
|
||
description: Event updated successfully.
|
||
|
||
delete:
|
||
summary: Delete an event.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
-
|
||
description: Event type
|
||
name: type
|
||
in: path
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- timed
|
||
- sequence
|
||
required: true
|
||
-
|
||
description: Event ID
|
||
name: id
|
||
in: path
|
||
schema:
|
||
type: integer
|
||
required: true
|
||
example: 1
|
||
responses:
|
||
"204":
|
||
description: The event no longer exists.
|
||
|
||
|
||
/project/{project}/label:
|
||
get:
|
||
summary: Get project labels.
|
||
tags: [ "project" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/Project"
|
||
responses:
|
||
"200":
|
||
description: List of project label definitions
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Label"
|
||
|
||
|
||
/project/{project}/configuration/{path}:
|
||
get:
|
||
summary: Get project configuration data.
|
||
tags: [ "project" ]
|
||
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"
|
||
]
|
||
}
|
||
"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" ]
|
||
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
|
||
|
||
|
||
/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" ]
|
||
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
|
||
"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.
|
||
|
||
|
||
/navdata:
|
||
get:
|
||
summary: Get navigation data.
|
||
tags: [ "navdata" ]
|
||
parameters:
|
||
- $ref: "#/components/parameters/QueryLimit"
|
||
- $ref: "#/components/parameters/QueryOffset"
|
||
responses:
|
||
"200":
|
||
description: List of navigation data items
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/NavData"
|
||
|
||
|
||
/navdata/gis/point:
|
||
get:
|
||
summary: Get navigation data as GeoJSON point features
|
||
tags: [ "navdata" ]
|
||
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"
|
||
|
||
|
||
/navdata/gis/line:
|
||
get:
|
||
summary: Get navigation data as GeoJSON line features
|
||
tags: [ "navdata" ]
|
||
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"
|
||
|
||
|
||
/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.
|
||
|
||
|
||
/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" ]
|