mirror of
https://gitlab.com/wgp/dougal/software.git
synced 2025-12-06 11:07:08 +00:00
Update API description
This commit is contained in:
D. Berge
@@ -1,6 +1,6 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
version: 0.2.0
|
||||
version: 0.3.0
|
||||
title: Dougal API
|
||||
description: >
|
||||
Public API of the Dougal seismic production & data analysis tool.
|
||||
@@ -141,6 +141,15 @@ components:
|
||||
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
|
||||
@@ -150,6 +159,24 @@ components:
|
||||
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
|
||||
|
||||
QueryLimit:
|
||||
description: Maximum number of results to return
|
||||
name: limit
|
||||
@@ -164,6 +191,19 @@ components:
|
||||
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"
|
||||
|
||||
|
||||
schemas:
|
||||
Duration:
|
||||
type: object
|
||||
@@ -510,48 +550,111 @@ components:
|
||||
- readOnly: true
|
||||
- description: Geometry of the planned line, as a GeoJSON linestring.
|
||||
|
||||
Event:
|
||||
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:
|
||||
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
|
||||
description: Event timestamp.
|
||||
sequence:
|
||||
type: number
|
||||
nullable: true
|
||||
geometry:
|
||||
$ref: "#/components/schemas/GeoJSONPoint"
|
||||
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:
|
||||
type: string
|
||||
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
|
||||
|
||||
EventAbstract:
|
||||
allOf:
|
||||
-
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: number
|
||||
description: Event ID.
|
||||
-
|
||||
$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.
|
||||
|
||||
SeisExportEntryFSP:
|
||||
type: object
|
||||
@@ -1002,6 +1105,42 @@ paths:
|
||||
$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.
|
||||
@@ -1125,6 +1264,14 @@ paths:
|
||||
$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: []
|
||||
@@ -1136,26 +1283,77 @@ paths:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Event"
|
||||
$ref: "#/components/schemas/EventNew"
|
||||
responses:
|
||||
"201":
|
||||
description: New event created successfully
|
||||
"401":
|
||||
$ref: "#/components/responses/401"
|
||||
put:
|
||||
summary: Update an existing event.
|
||||
|
||||
/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/Event"
|
||||
$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.
|
||||
@@ -1163,98 +1361,17 @@ paths:
|
||||
$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"
|
||||
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.
|
||||
"401":
|
||||
$ref: "#/components/responses/401"
|
||||
|
||||
|
||||
/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.
|
||||
"401":
|
||||
$ref: "#/components/responses/401"
|
||||
|
||||
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
|
||||
- $ref: "#/components/parameters/EventID"
|
||||
responses:
|
||||
"204":
|
||||
description: The event no longer exists.
|
||||
@@ -1483,6 +1600,40 @@ paths:
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user