openapi_legacy.yaml

openapi: 3.0.2
info:
  title: OSRD Editoast
  description: OSRD Edition service description
  version: 0.1.0

tags:
  - name: infra
    description: Infra
  - name: routes
    description: Operations related to infra routes
  - name: timetable
    description: Timetable
  - name: pathfinding
    description: Pathfinding operations
  - name: layers
    description: Map layers
  - name: electrical_profiles
    description: Electrical profiles
  - name: train_schedule
    description: Train Schedule

paths:
  /infra/:
    post:
      tags:
        - infra
      summary: Create an infra
      requestBody:
        description: Name of the infra to create
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        201:
          description: The created infra
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Infra"

  /infra/{id}/:
    post:
      tags:
        - infra
      summary: Update/Create/Delete an object of the infra
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
      requestBody:
        description: Operations to do on the infra
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Operation"
      responses:
        200:
          description: An array containing infos about the operations processed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RailjsonObject"

  /infra/{id}/errors/:
    get:
      tags:
        - infra
      summary: Retrieve a paginated list of errors
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: infra id
          required: true
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: The page number
        - in: query
          name: page_size
          schema:
            type: integer
            default: 25
            minimum: 10
          description: The number of item per page
        - in: query
          name: error_type
          schema:
            $ref: "#/components/schemas/InfraErrorType"
          description: The type of error to filter on
        - in: query
          name: object_id
          schema:
            type: string
          description: errors and warnings that only part of a given object
        - in: query
          name: level
          schema:
            type: string
            enum: [errors, warnings, all]
            default: all
          description: Whether the response should include errors or warnings
      responses:
        200:
          description: A paginated list of errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of elements
                    example: 1
                  next:
                    type: integer
                    nullable: true
                    example: null
                    description: The index of the following page (null if no more pages available)
                  previous:
                    type: integer
                    nullable: true
                    example: null
                    description: The index of the previous page (null if requesting the first page)
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/InfraError"

  /infra/refresh/:
    post:
      tags:
        - infra
      summary: Refresh the layers
      parameters:
        - in: query
          name: infras
          schema:
            type: array
            items:
              type: integer
            default: []
          description: A list of infra ID
        - in: query
          name: force
          schema:
            type: boolean
            default: false
          description: Force the refresh of the layers
      responses:
        200:
          description: A list thats contains the ID of the infras that were refreshed*
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer

  /infra/{id}/objects/{object_type}/:
    post:
      tags:
        - infra
      summary: "Retrieve a list of specific objects in railjson format"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: Infra id
          required: true
        - in: path
          name: object_type
          schema:
            $ref: "#/components/schemas/ObjectType"
          description: The type of the object
          required: true
      requestBody:
        description: List of object id's
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        200:
          description: No content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - railjson
                    - geographic
                  properties:
                    railjson:
                      description: Object properties in railjson format
                      $ref: "#/components/schemas/Railjson"
                    geographic:
                      description: object's geographic in geojson format
                      $ref: "#/components/schemas/Geometry"


components:
  schemas:
    RailjsonObject:
      required:
        - obj_type
        - railjson
      properties:
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        railjson:
          $ref: "#/components/schemas/Railjson"

    DeleteOperation:
      required:
        - operation_type
        - obj_type
        - obj_id
      properties:
        operation_type:
          type: string
          enum:
            - DELETE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        obj_id:
          type: string
          example: bd840b06-84ba-4566-98c1-ccf0196c5f16

    UpdateOperation:
      required:
        - operation_type
        - obj_type
        - railjson_patch
      properties:
        operation_type:
          type: string
          enum:
            - UPDATE
        obj_type:
          $ref: "#/components/schemas/ObjectType"
        obj_id:
          type: string
          example: bd840b06-84ba-4566-98c1-ccf0196c5f16
        railjson_patch:
          $ref: "#/components/schemas/Patches"

    Patch:
      description: A JSONPatch document as defined by RFC 6902
      required:
        - "op"
        - "path"
      properties:
        op:
          type: string
          description: The operation to be performed
          enum:
            - "add"
            - "remove"
            - "replace"
            - "move"
            - "copy"
            - "test"
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          description: The value to be used within the operations.
        from:
          type: string
          description: A string containing a JSON Pointer value.

    Patches:
      type: array
      description: A list of Patch
      items:
        $ref: "#/components/schemas/Patch"

    Railjson:
      type: object
      description: This field follows railjson format
      additionalProperties: true
      required:
        - id
      properties:
        id:
          type: string
      example:
        id: bd840b06-84ba-4566-98c1-ccf0196c5f16
        geo:
          type: LineString
          coordinates:
            - - 1.0
              - 41.0
            - - 2.0
              - 42.0
        curves: []
        length: 1000
        slopes:
          - end: 500
            begin: 250
            gradient: -1
        line_code: 1
        line_name: my line
        track_name: track name
        navigability: BOTH
        track_number: 1

    InfraErrorType:
      type: string
      description: Type of the infra error
      enum:
        - duplicated_group
        - empty_object
        - invalid_group
        - invalid_reference
        - invalid_route
        - invalid_switch_ports
        - missing_route
        - missing_buffer_stop
        - object_out_of_path
        - odd_buffer_stop_location
        - out_of_range
        - overlapping_speed_sections
        - overlapping_switches
        - overlapping_electrifications
        - unknown_port_name
        - unused_port
        - node_endpoints_not_unique

    InfraError:
      type: object
      description: An infra error or warning
      required: [information]
      properties:
        geographic:
          nullable: true
          description: Geojson of the geographic geometry of the error
          $ref: "#/components/schemas/Geometry"
        information:
          type: object
          description: Information about the error (check schema documentation for more details)
          required: [obj_id, obj_type, error_type, is_warning]
          properties:
            obj_id:
              type: string
            obj_type:
              type: string
              enum:
                - TrackSection
                - Signal
                - BufferStop
                - Detector
                - Switch
                - Route
            error_type:
              $ref: "#/components/schemas/InfraErrorType"
            field:
              type: string
            is_warning:
              type: boolean

    Geometry:
      type: object
      description: Definition of a GeoJSON geometry
      oneOf:
        - $ref: "#/components/schemas/Point"
        - $ref: "#/components/schemas/LineString"
        - $ref: "#/components/schemas/Polygon"
        - $ref: "#/components/schemas/MultiPoint"
        - $ref: "#/components/schemas/MultiLineString"
        - $ref: "#/components/schemas/MultiPolygon"

    Point3D:
      type: array
      description: Point in 3D space
      minItems: 2
      maxItems: 3
      items:
        type: number

    Point:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Point
        coordinates:
          $ref: "#/components/schemas/Point3D"

    LineString:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - LineString
        coordinates:
          type: array
          items:
            $ref: "#/components/schemas/Point3D"

    Polygon:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Polygon
        coordinates:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/Point3D"

    MultiPoint:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPoint
        coordinates:
          type: array
          items:
            $ref: "#/components/schemas/Point3D"

    MultiLineString:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiLineString
        coordinates:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/Point3D"

    MultiPolygon:
      type: object
      description: GeoJSon geometry
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                $ref: "#/components/schemas/Point3D"

    SpaceTimePosition:
      type: object
      properties:
        time: { type: number, format: float }
        position: { type: number, format: float }
      required: [time, position, speed]