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:
* `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.
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.
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.
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.
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`)
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.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
"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.
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.
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.
