mirror of
https://gitlab.com/wgp/dougal/software.git
synced 2025-12-06 12:47:08 +00:00
2163 lines
91 KiB
YAML
2163 lines
91 KiB
YAML
openapi: 3.0.0
|
||
info:
|
||
version: 0.3.1
|
||
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.
|
||
|
||
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:
|
||
"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
|
||
|
||
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"
|
||
|
||
Unique:
|
||
description: |
|
||
Return unique results. Any value at all represents `true`.
|
||
name: unique
|
||
in: query
|
||
schema:
|
||
type: string
|
||
pattern: ".+"
|
||
example: "t"
|
||
|
||
|
||
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.
|
||
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.
|
||
|
||
|
||
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/EventChangesIsDeletedAbstract"
|
||
|
||
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
|
||
}
|
||
|
||
|
||
|
||
security:
|
||
- BearerAuthUser: []
|
||
- CookieAuthUser: []
|
||
|
||
paths:
|
||
|
||
/project:
|
||
get:
|
||
description: Get list of projects.
|
||
tags: [ "project" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
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/401"
|
||
|
||
/project/{project}:
|
||
# Synonym: /project/{project}/summary:
|
||
get:
|
||
description: Get details about a specific project.
|
||
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:
|
||
description: Get list of preplot lines.
|
||
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.
|
||
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:
|
||
description: Get list of sequences.
|
||
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:
|
||
description: Get a sequence
|
||
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.
|
||
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
|
||
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:
|
||
description: Get list of planned sequences.
|
||
tags: [ "planner" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
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
|
||
"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.
|
||
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.
|
||
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:
|
||
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.
|
||
"401":
|
||
$ref: "#/components/responses/401"
|
||
|
||
|
||
/project/{project}/event:
|
||
get:
|
||
summary: Get project events.
|
||
tags: [ "log" ]
|
||
security:
|
||
- BearerAuthGuest: []
|
||
- CookieAuthGuest: []
|
||
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"
|
||
"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.
|
||
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.
|
||
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.
|
||
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`.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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.
|
||
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"
|
||
|
||
|
||
/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.
|
||
|
||
|
||
|
||
|
||
|
||
/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" ]
|