HyperLeda API specification 1.0.0#

admin#

GET /ping#

Test that service is up and running

Response 200 OK

application/json

{
    "data": {
        "ping": "pong"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/PingResponseSchema"
        }
    }
}

POST /api/v1/admin/source#

New source entry

Description

Creates new source entry in the database for internal communication and unpublished articles.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "title": "string",
    "authors": [
        "string"
    ],
    "year": 2006
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "title": {
            "type": "string",
            "description": "Title of publication"
        },
        "authors": {
            "type": "array",
            "description": "List of authors",
            "items": {
                "type": "string"
            }
        },
        "year": {
            "type": "integer",
            "minimum": 1500,
            "description": "Year of the publication",
            "example": 2006
        }
    },
    "required": [
        "authors",
        "title",
        "year"
    ]
}

Response 200 OK

application/json

{
    "data": {
        "code": "string"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/CreateSourceResponseSchema"
        }
    }
}

POST /api/v1/admin/task#

Start processing task

Description

Starts background task.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "task_name": "echo",
    "payload": {
        "sleep_time_seconds": 2
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "task_name": {
            "type": "string",
            "description": "Name of the task to start",
            "example": "echo"
        },
        "payload": {
            "type": "object",
            "description": "Payload to the task",
            "example": {
                "sleep_time_seconds": 2
            },
            "additionalProperties": {}
        }
    },
    "required": [
        "task_name"
    ]
}

Response 200 OK

application/json

{
    "data": {
        "code": "string"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/CreateSourceResponseSchema"
        }
    }
}

GET /api/v1/admin/task#

Get information about the task

Description

Retrieves information about the task using its id.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token
`task_id`	query	integer		No	ID of the task

Response 200 OK

application/json

{
    "data": {
        "id": 0,
        "task_name": "string",
        "status": "string",
        "payload": {},
        "start_time": "2022-04-13T15:42:05.901Z",
        "end_time": "2022-04-13T15:42:05.901Z",
        "message": {}
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/GetTaskInfoResponseSchema"
        }
    }
}

POST /api/v1/admin/table#

Get or create schema for the table.

Description

Creates new schema for the table which can later be used to upload data.

Important: If the table with the specified name already exists, does nothing and returns ID of the previously created table without any alterations.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

⚠️ This example has been generated automatically from href="#__codelineno-12-1">{ "table_name": "string", "columns": [ { "name": "name", "data_type": "str", "ucd": "meta.id" }, { "name": "ra", "data_type": "float", "unit": "hourangle", "ucd": "pos.eq.ra" }, { "name": "dec", "data_type": "float", "unit": "deg", "ucd": "pos.eq.dec" } ], "bibcode": "2024PDU....4601628D", "datatype": "regular", "description": "string" } the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "table_name": {
            "type": "string",
            "description": "Name of the table"
        },
        "columns": {
            "type": "array",
            "description": "List of columns in the table",
            "example": [
                {
                    "name": "name",
                    "data_type": "str",
                    "ucd": "meta.id"
                },
                {
                    "name": "ra",
                    "data_type": "float",
                    "unit": "hourangle",
                    "ucd": "pos.eq.ra"
                },
                {
                    "name": "dec",
                    "data_type": "float",
                    "unit": "deg",
                    "ucd": "pos.eq.dec"
                }
            ],
            "items": {
                "$ref": "#/components/schemas/ColumnDescription"
            }
        },
        "bibcode": {
            "type": "string",
            "description": "ADS bibcode of the article that published the data (or code of the internal communication)",
            "example": "2024PDU....4601628D"
        },
        "datatype": {
            "type": "string",
            "default": "regular",
            "enum": [
                "regular",
                "reprocessing",
                "preliminary",
                "compilation",
                null
            ],
            "description": "Type of the data in the table",
            "nullable": true
        },
        "description": {
            "type": "string",
            "default": "",
            "description": "Human-readable description of the table",
            "nullable": true
        }
    },
    "required": [
        "bibcode",
        "columns",
        "table_name"
    ]
}

Response 200 OK

application/json

{
    "data": {
        "id": 0
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/CreateTableResponseSchema"
        }
    }
}

Response 201 Created

application/json

{
    "data": {
        "id": 0
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/CreateTableResponseSchema"
        }
    }
}

POST /api/v1/admin/table/data#

Add new raw data to the table

Description

Inserts new data to the table.

Deduplicates the rows based on their contents. If the two rows were identical this method will only insert the last one.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "table_id": 0,
    "data": [
        {
            "name": "M 33",
            "ra": 1.5641,
            "dec": 30.6602
        },
        {
            "name": "M 31",
            "ra": 0.7123,
            "dec": 41.269
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "table_id": {
            "type": "integer",
            "description": "ID of the table to add data to"
        },
        "data": {
            "type": "array",
            "description": "\n            Actual data to append. \n            Keys in this dictionary must be a subset of the columns in the table. \n            If not specified, column will be set to NULL.\n        ",
            "example": [
                {
                    "name": "M 33",
                    "ra": 1.5641,
                    "dec": 30.6602
                },
                {
                    "name": "M 31",
                    "ra": 0.7123,
                    "dec": 41.269
                }
            ],
            "items": {
                "type": "object",
                "additionalProperties": {}
            }
        }
    },
    "required": [
        "data",
        "table_id"
    ]
}

Response 200 OK

application/json

{
    "data": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/AddDataResponseSchema"
        }
    }
}

POST /api/v1/admin/table/process#

Start processing of the table

Description

Starts different processing steps on the table: for example, homogenization and cross-identification.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "table_id": 0,
    "cross_identification": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "table_id": {
            "type": "integer",
            "description": "Identifier of the table"
        },
        "cross_identification": {
            "description": "Cross-identification parameters for the processing",
            "allOf": [
                {
                    "$ref": "#/components/schemas/CrossIdentification"
                }
            ]
        }
    },
    "required": [
        "table_id"
    ]
}

Response 200 OK

application/json

{
    "data": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/TableProcessResponseSchema"
        }
    }
}

GET /api/v1/table/status/stats#

Get statistics on table processing

Description

Accesses the current status of the processing of a given table. Returns the distribution of objects by processing status.

If there are no objects with the given status, it will not be present in the response.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token
`table_id`	query	integer		No	Identifier of the table

Response 200 OK

application/json

{
    "data": {
        "processing": {}
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/TableStatusStatsResponseSchema"
        }
    }
}

POST /api/v1/admin/table/status#

Set status of the table

Description

Set status of the table and its objects.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`TokenAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "table_id": 0,
    "overrides": [
        {
            "id": "55732268-9f91-4b8b-8b48-0677f6c0f95f",
            "pgc": 0
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "table_id": {
            "type": "integer",
            "description": "Identifier of the table"
        },
        "overrides": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Overrides"
            }
        }
    },
    "required": [
        "table_id"
    ]
}

Response 200 OK

application/json

{
    "data": {}
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/SetTableStatusResponseSchema"
        }
    }
}

source#

GET /api/v1/source#

Get information about source

Description

Retrieves information about the source using its id

Input parameters

Parameter	In	Type	Default	Nullable	Description
`id`	query	integer		No	HyperLeda source id

Response 200 OK

application/json

{
    "data": {
        "code": "string",
        "title": "string",
        "authors": [
            "string"
        ],
        "year": 0
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/GetSourceResponseSchema"
        }
    }
}

authentication#

POST /api/v1/login#

Login user with username and password

Description

Gives user credentials for authentication in handlers

Request body

application/json

{
    "username": "string",
    "password": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "properties": {
        "username": {
            "type": "string",
            "description": "Username"
        },
        "password": {
            "type": "string",
            "description": "Password"
        }
    },
    "required": [
        "password",
        "username"
    ]
}

Response 200 OK

application/json

{
    "data": {
        "token": "string"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "properties": {
        "data": {
            "$ref": "#/components/schemas/LoginResponseSchema"
        }
    }
}

Schemas#

AddDataRequestSchema#

Name	Type
`data`	Array<>
`table_id`	integer

AddDataResponseSchema#

ColumnDescription#

Name	Type
`data_type`	string
`description`	string\| null
`name`	string
`ucd`	string\| null
`unit`	string\| null

CreateSourceRequestSchema#

Name	Type
`authors`	Array<string>
`title`	string
`year`	integer

CreateSourceResponseSchema#

Name	Type
`code`	string

CreateTableRequestSchema#

Name	Type
`bibcode`	string
`columns`	Array<ColumnDescription>
`datatype`	string\| null
`description`	string\| null
`table_name`	string

CreateTableResponseSchema#

Name	Type
`id`	integer

CrossIdentification#

Name	Type
`inner_radius_arcsec`	number
`outer_radius_arcsec`	number

GetSourceRequestSchema#

Name	Type
`id`	integer

GetSourceResponseSchema#

Name	Type
`authors`	Array<string>
`code`	string
`title`	string
`year`	integer

GetTaskInfoRequestSchema#

Name	Type
`task_id`	integer

GetTaskInfoResponseSchema#

Name	Type
`end_time`	string(date-time)
`id`	integer
`message`
`payload`
`start_time`	string(date-time)
`status`	string
`task_name`	string

LoginRequestSchema#

Name	Type
`password`	string
`username`	string

LoginResponseSchema#

Name	Type
`token`	string

Overrides#

Name	Type
`id`	string(uuid)
`pgc`	integer

PingRequestSchema#

PingResponseSchema#

Name	Type
`ping`	string

SetTableStatusRequestSchema#

Name	Type
`overrides`	Array<Overrides>
`table_id`	integer

SetTableStatusResponseSchema#

StartTaskRequestSchema#

Name	Type
`payload`	Example: `{'sleep_time_seconds': 2}`
`task_name`	string

StartTaskResponseSchema#

Name	Type
`id`	integer

TableProcessRequestSchema#

Name	Type
`cross_identification`
`table_id`	integer

TableProcessResponseSchema#

TableStatusStatsRequestSchema#

Name	Type
`table_id`	integer

TableStatusStatsResponseSchema#

Name	Type
`processing`

Security schemes#

Name	Type	Scheme	Description
TokenAuth	http	bearer