openapi: 3.0.0
servers:
  - description: OSDB demo server
    url: https://osdb.openlinksw.com/osdb
info:
  contact:
    email: osdb@openlinksw.com
    x-twitter: OpenLink
  description: An OpenAPI description of the OpenLink Smart Data Bot REST API v1
  license:
    name: CC-BY-SA
    url: https://creativecommons.org/licenses/by-sa/3.0/legalcode
  title: OSDB REST API v1
  version: 1.0.0
  x-apisguru-categories:
    - developer_tools
  x-logo:
    url: https://twitter.com/OpenLink/profile_image?size=original
  x-origin:
    - converter:
        url: https://github.com/mermade/oas-kit
        version: 7.0.4
      format: openapi
      url: https://osdb.openlinksw.com/osdb/osdb_rest_api.openapi.json
      version: "3.0"
  x-providerName: openlinksw.com
  x-serviceName: osdb
paths:
  "/api/v1/actions/{serviceId}":
    get:
      description: Returns an array of action descriptions for the actions supported by the given service
      operationId: listActions
      parameters:
        - description: Service ID of the service for which actions are to be listed
          in: path
          name: serviceId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/actions/:service_id
                method: list_actions
                response:
                  - action_id: read
                    description: List a container's details and contents
                    entry_point:
                      content_types:
                        - application/ld+json
                        - text/turtle
                      description: Retrieve a description of an LDP resource or container
                      encoding_types: null
                      http_method: GET
                      name: LDP Read - Retrieve a resource description
                      parameters:
                        - description: The URL of an LDPR or LDPC. LDPCs must be terminated by /
                          display_name: Resource URL
                          parameter_name: ldpResourceUri
                          permitted_values: null
                          required: 1
                          type: uri
                      url: null
                      url_template: (ldpResourceUri)
                  - action_id: update
                    description: Update an LDP RDF resource
                    entry_point:
                      content_types:
                        - text/html
                      description: Update an RDF resource (LDP-RS) including containers (LDPCs)
                      encoding_types:
                        - text/turtle
                      http_method: PUT
                      name: LDP-RS Update - Update an RDF resource
                      parameters:
                        - description: The URL of an LDPR or LDPC. LDPCs must be terminated by /
                          display_name: Resource URL
                          parameter_name: ldpResourceUri
                          permitted_values: null
                          required: 1
                          type: uri
                      url: null
                      url_template: (ldpResourceUri)
                  - action_id: delete
                    description: Delete an LDP resource
                    entry_point:
                      content_types: ""
                      description: Deletes an LDP resource or container
                      encoding_types: null
                      http_method: DELETE
                      name: LDP Delete - Delete an LDP resource
                      parameters:
                        - description: The URL of an LDPR or LDPC. LDPCs must be terminated by /
                          display_name: Resource URL
                          parameter_name: ldpResourceUri
                          permitted_values: null
                          required: 1
                          type: uri
                      url: null
                      url_template: (ldpResourceUri)
                  - action_id: create
                    description: Create an LDP RDF resource
                    entry_point:
                      content_types:
                        - text/html
                      description: Create an RDF resource (LDP-RS) including containers (LDPCs)
                      encoding_types:
                        - text/turtle
                      http_method: POST
                      name: LDP-RS Create - Create an RDF resource
                      parameters:
                        - description: The suggested name (slug) for the new resource
                          display_name: Suggested name
                          parameter_name: Slug
                          permitted_values: null
                          required: 1
                          type: header
                        - description: The URL of an LDPR or LDPC. LDPCs must be terminated by /
                          display_name: Resource URL
                          parameter_name: ldpResourceUri
                          permitted_values: null
                          required: 1
                          type: uri
                      url: null
                      url_template: (ldpResourceUri)
                status: success
              schema:
                $ref: "#/components/schemas/ListActionsResponse"
          description: An array of action descriptions for the actions supported by the given service.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: List actions
      tags:
        - OSDB
  "/api/v1/actions/{serviceId}/{actionId}":
    get:
      description: Returns a description of a given service action.
      operationId: describeAction
      parameters:
        - description: Service ID of the service supporting the action.
          in: path
          name: serviceId
          required: true
          schema:
            type: string
        - description: Action ID of the action to describe.
          in: path
          name: actionId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/actions/:service_id/:action_id
                method: describe_action
                response:
                  action_id: products
                  description: Returns information about the Uber products offered at a given location
                  entry_point:
                    content_types:
                      - application/json
                      - text/turtle
                      - application/rdf+xml
                      - application/ld+json
                    description: "The Products endpoint returns information about the Uber products offered at a given location.\ 

                      \    The response includes the display name and other details about each product.

                      \   \ 

                      \    This endpoint does not reflect real-time availability of the products. Please use the Time\ 

                      \    Estimates endpoint to determine real-time availability and ETAs of products.


                      \    In some markets, the list of products returned from this endpoint may vary by the time of\ 

                      \    day due to time restrictions on when that product may be utilized.

                      \   "
                    encoding_types: null
                    http_method: GET
                    name: Products — Uber products at a given location
                    parameters:
                      - description: Longitude component of location
                        display_name: Longitude
                        parameter_name: longitude
                        permitted_values: null
                        required: 1
                        type: query
                      - description: Latitude component of location
                        display_name: Latitude
                        parameter_name: latitude
                        permitted_values: null
                        required: 1
                        type: query
                    url: https://sandbox-api.uber.com/v1/products
                    url_template: https://sandbox-api.uber.com/v1/products(?latitude,longitude)
                status: success
              schema:
                $ref: "#/components/schemas/DescribeActionResponse"
          description: A single action description
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Describe action
      tags:
        - OSDB
  "/api/v1/actions/{serviceId}/{actionId}/exec":
    post:
      description: |-
        Executes a registered service action and returns any output from the action.
        The data returned in the POST response body may be: 
        * the raw action output, 
        * a URL encapsulating the action request which executes the action when dereferenced  (only for actions using GET), 
        * RDF generated from the action output,
        * a URL to an RDF viewer's display of the generated RDF.

        Any parameters required by the action are supplied as a JSON object in the POST body. The parameter types supported are: "query", "header", "uri", "path" and "body".  The parameter type determines where a supplied parameter value is inserted into the HTTP request constructed by OSDB to invoke the target service action. In addition to native parameters required by the service action, 'Execute action' accepts some OSDB-specific parameters.<br/><br/>

        **Examples**
        * ```curl -ik -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec```  
        * ```curl -ikL -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823", "osdb:output_type":"generate_rdf", "osdb:response_format":"application/rdf+xml" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec``` 
        * ```curl -ikL -X POST -d '{ "latitude":"37.7759792", "longitude":"-122.41823", "osdb:output_type":"display_rdf" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/uber/products/exec``` 
        * ```curl -ik -X POST -d '{ "q":"skiing", "osdb:response_format": "application/rdf+xml" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search/exec``` 
        * ```curl -ik -X POST -d '{ "q":"skiing", "osdb:output_type": "url_only" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/facet/search/exec``` 
        * ```curl -ik -X POST -d '{ "Content-Location": "http://demo.openlinksw.co.uk/pubs", "osdb:body_data_src_url": "http://ods-qa.openlinksw.com/DAV/home/osdb/pubs.csv", "extractor": "csv", "osdb:response_format": "application/rdf+xml", "osdb:body_data_encoding": "text/csv" }' -H 'Content-Type: application/json' https://osdb.openlinksw.com/osdb/api/v1/actions/csv_transformer/transform/exec```
      operationId: executeAction
      parameters:
        - description: Service ID of the service supporting the action.
          in: path
          name: serviceId
          required: true
          schema:
            type: string
        - description: Action ID of the action to execute.
          in: path
          name: actionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            examples:
              example1_uber_products:
                value:
                  latitude: "37.7759792"
                  longitude: "-122.41823"
            schema:
              $ref: "#/components/schemas/ExecBody"
        description: Any parameters required by the action are supplied as a JSON object in the request body. The properties of this object depend on the service action being invoked.
      responses:
        2XX:
          content:
            "*/*":
              example:
                description: The response from an action varies depending on the target service invoked by the action.
          description: Response from an OSDB action invocation.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Execute action
      tags:
        - OSDB
  "/api/v1/actions/{serviceId}/{actionId}/help":
    get:
      description: Returns the help text for a given service action
      operationId: actionHelp
      parameters:
        - description: Service ID of the service supporting the action.
          in: path
          name: serviceId
          required: true
          schema:
            type: string
        - description: Action ID of the action for which help text is being requested.
          in: path
          name: actionId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/actions/:service_id/:action_id/help
                method: action_help
                response:
                  action_id: search
                  help_text: |
                    
                    Action options:

                    -s, --same_as [same_as]
                    	Enables owl:sameAs inferencing for facet search
                    	Required: no
                    	Permitted values: yes
                    -v, --view_type [view_type]
                    	Sets the default view orientation
                    	Required: no
                    	Permitted values: entity-types, attribute-names
                    -l, --limit [limit]
                    	Limits the number of result set entities returned
                    	Required: no
                    -o, --offset [offset]
                    	Sets the result set page size for scrolling
                    	Required: no
                    -q, --q <q>
                    	A word or phrase to be used for the Facet free text search. Multiple words should be delimited by '+'
                    	Required: yes
                    -u, --url_only [url_only]
                    	Return only the action URL, not the action results
                    	Required: no
                    -r, --response_format [response_format]
                    	Sets the response media type through an Accept header.
                    	Required: no
                    	Permitted values: application/json, application/rdf+xml, text/html, text/turtle
                    -t, --quality_values [quality_values]
                    	Quality value string. e.g. application/json;q=1.0,text/turtle;q=0.8,*/*;q=0.5. 
                    	--response_format takes precedence.
                    	Required: no
                  service_id: facet
                status: success
              schema:
                $ref: "#/components/schemas/ActionHelpResponse"
          description: Action help text
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Action help
      tags:
        - OSDB
  /api/v1/login:
    get:
      description: Logs a user into the OSDB server, authenticating them by their WebID and returning an OSDB session ID in cookie osdb.sid
      operationId: login
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/login
                method: login
                response:
                  user: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.ttl#identity
                status: success
              schema:
                $ref: "#/components/schemas/LoginResponse"
          description: Confirmation of a successful OSDB login.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Login
      tags:
        - OSDB
  /api/v1/logout:
    get:
      description: Logs a user out of the OSDB server, ending their OSDB session
      operationId: logout
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/logout
                method: logout
                response:
                  user: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/cmsb_ex_webid_170223.ttl#identity
                status: success
              schema:
                $ref: "#/components/schemas/LogoutResponse"
          description: Confirmation of a successful OSDB logout.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Logout
      tags:
        - OSDB
  /api/v1/services:
    get:
      description: Returns descriptions of all services registered with the OSDB server.
      operationId: listServices
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/services
                method: list_services
                response:
                  - description: Host-independent Linked Data Platform service
                    import_source_uri: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/ldp_svc.host_independent.ttl
                    service_id: ldp_generic
                    service_name: LDP generic
                  - description: null
                    import_source_uri: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/fct_svc.ki.170103.cmsb.ttl
                    service_id: anonymous_facet
                    service_name: anonymous_facet
                status: success
              schema:
                $ref: "#/components/schemas/ListServicesResponse"
          description: An array of service descriptions for all services registered with the OSDB server
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: List services
      tags:
        - OSDB
    post:
      description: Loads a service description into the OSDB Service Registry
      operationId: loadService
      requestBody:
        content:
          application/json:
            example:
              service_description_url: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/csv_extractor_svc.ods-qa.170109.ttl
              service_moniker: csv_extractor
            schema:
              properties:
                service_description_url:
                  description: The URL of the resource containing the service description to load.
                  type: string
                service_moniker:
                  description: "Service ID to be used to uniquely identify the service. (Optional: Required for anonymous services or to override the service name in the service description.)"
                  type: string
              required:
                - service_description_url
              type: object
        description: Service to register with OSDB
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/services
                method: load_service
                response: Loaded service description
                status: success
              schema:
                properties:
                  api:
                    description: The path of the REST API method
                    type: string
                  method:
                    description: The name of the REST API method
                    type: string
                  response:
                    description: Confirmation message
                    type: string
                  status:
                    default: success
                    enum:
                      - success
                    type: string
                required:
                  - status
                  - method
                  - api
                  - response
                type: object
          description: loadService response
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Load service
      tags:
        - OSDB
  "/api/v1/services/{serviceId}":
    delete:
      description: Removes a service description from the OSDB Service Registry
      operationId: unloadService
      parameters:
        - description: Service ID of the service to be unloaded
          in: path
          name: serviceId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/services
                method: unload_service
                response: Unloaded service csv_transformer from the Service Registry
                status: success
              schema:
                properties:
                  api:
                    description: The path of the REST API method
                    type: string
                  method:
                    description: The name of the REST API method
                    type: string
                  response:
                    description: Confirmation message
                    type: string
                  status:
                    default: success
                    enum:
                      - success
                    type: string
                required:
                  - status
                  - method
                  - api
                  - response
                type: object
          description: unloadService response
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Unload service
      tags:
        - OSDB
    get:
      description: Returns a description of a given service
      operationId: describeService
      parameters:
        - description: Service ID of the service to describe.
          in: path
          name: serviceId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                api: /osdb/api/v1/services/:service_id
                method: describe_service
                response:
                  description: Host-independent Linked Data Platform service
                  import_source_uri: http://ods-qa.openlinksw.com:8896/DAV/home/nobody/ldp_svc.host_independent.ttl
                  service_id: ldp_generic
                  service_name: LDP generic
                status: success
              schema:
                $ref: "#/components/schemas/DescribeServiceResponse"
          description: A single service description
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error response
      summary: Describe service
      tags:
        - OSDB
components:
  schemas:
    ActionDescription:
      properties:
        action_id:
          description: A unique one word identifier for the action.
          type: string
        description:
          description: A short description of the action.
          type: string
        entry_point:
          $ref: "#/components/schemas/EntryPoint"
      required:
        - action_id
        - entry_point
      type: object
    ActionHelp:
      properties:
        action_id:
          description: A unique one word identifier for the action.
          type: string
        help_text:
          description: The help text for the action.
          type: string
        service_id:
          description: A unique one word identifier for the service.
          type: string
      required:
        - service_id
        - action_id
        - help_text
      type: object
    ActionHelpResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          $ref: "#/components/schemas/ActionHelp"
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    DescribeActionResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          $ref: "#/components/schemas/ActionDescription"
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    DescribeServiceResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          $ref: "#/components/schemas/ServiceDescription"
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    EntryPoint:
      properties:
        content_types:
          description: The supported MIME type(s) for an EntryPoint response.
          items:
            type: string
          type: array
        description:
          description: A short description of the action. Optional - may be null.
          type: string
        encoding_types:
          description: The supported MIME type(s) for an EntryPoint request. Null if not applicable.
          items:
            type: string
          type: array
        http_method:
          description: The HTTP method used by the EntryPoint.
          enum:
            - GET
            - PUT
            - POST
            - DELETE
          type: string
        name:
          description: A word or short phrase to be used as the action's display name. Optional - may be null.
          type: string
        parameters:
          description: Descriptions of the EntryPoint parameters. Null if not applicable.
          items:
            $ref: "#/components/schemas/EntryPointParameter"
          type: array
        url:
          description: The EntryPoint URL. It will be non-null if url_template is null.
          format: uri
          type: string
        url_template:
          description: The EntryPoint's URL template. Only required if the entry point URL is parameterized. Property 'url' will be null if url_template is non-null.
          format: uri-template
          type: string
      required:
        - http_method
        - url
        - url_template
        - name
        - description
        - encoding_types
        - content_types
        - parameters
      type: object
    EntryPointParameter:
      properties:
        description:
          description: A short description of the parameter for use in the OSDB Action Console. Optional - may be null.
          type: string
        display_name:
          description: The parameter's display name in the OSDB Action Console. Optional - may be null.
          type: string
        parameter_name:
          description: The parameter name as present in the HTTP request. e.g. the key name in a query string key-value pair.
          type: string
        permitted_values:
          description: If the parameter accepts only a limited set of values, the allowed set of values. Null if not applicable.
          items:
            type: string
          type: array
        required:
          description: A flag indicating if the parameter is optional.
          format: int32
          maximum: 1
          minimum: 0
          type: integer
        type:
          description: The type of the parameter, indicating its location in the HTTP request.
          enum:
            - query
            - header
            - uri
            - path
            - body
          type: string
      required:
        - parameter_name
        - display_name
        - description
        - type
        - required
        - permitted_values
      type: object
    ErrorModel:
      properties:
        api:
          description: The path of the REST API method reporting the error
          type: string
        method:
          description: The name of the REST API method reporting the error
          type: string
        response:
          description: A message describing the error
          type: string
        status:
          default: error
          enum:
            - error
          type: string
      type: object
    ExecBody:
      properties:
        action_specific_property1:
          description: An example action specific property. There may be 0, 1 or more action specific properties, each holding an action specific parameter value.
          type: string
        action_specific_property2:
          description: An example action specific property. There may be 0, 1 or more action specific properties, each holding an action specific parameter value.
          type: string
        osdb:body_data_encoding:
          description: The media type of the data associated with osdb:body_data_raw or osdb:body_data_src_url. In the case of osdb:body_data_raw, this is the media type before base64 encoding.
          type: string
        osdb:body_data_raw:
          description: Input data for the action (e.g. CSV data). The data must be base64 encoded by the client. Alternatively, clients can use osdb:body_data_src_url to supply the input data via a web-accessible document.
          format: byte
          type: string
        osdb:body_data_src_url:
          description: URL of a resource containing input data for the action (e.g. CSV data). Clients can instead use osdb:body_data_raw to supply the input data directly.
          format: uri
          type: string
        osdb:output_type:
          description: An OSDB-specific parameter controlling the action output type. If omitted, the native action output is returned.
          enum:
            - url_only
            - generate_rdf
            - display_rdf
          type: string
        osdb:response_format:
          description: Preferred response MIME type. This must be an output MIME type supported natively by the action or, if 'osdb:output_type' is set to 'generate_rdf', a Virtuoso Sponger output format. i.e. 'application/ld+json', 'text/turtle' or 'application/rdf+xml'.
          type: string
      type: object
    ListActionsResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          items:
            $ref: "#/components/schemas/ActionDescription"
          type: array
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    ListServicesResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          items:
            $ref: "#/components/schemas/ServiceDescription"
          type: array
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    LoginResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          properties:
            user:
              description: The WebID of the user who has logged in.
              type: string
          required:
            - user
          type: object
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    LogoutResponse:
      properties:
        api:
          description: The path of the REST API method
          type: string
        method:
          description: The name of the REST API method
          type: string
        response:
          properties:
            user:
              description: The WebID of the user who has logged out.
              type: string
          required:
            - user
          type: object
        status:
          default: success
          enum:
            - success
          type: string
      required:
        - status
        - method
        - api
        - response
      type: object
    ServiceDescription:
      properties:
        description:
          description: A short description of the service.
          type: string
        import_source_uri:
          description: The URI of the source service description document used to load the service into OSDB.
          format: uri
          type: string
        service_id:
          description: A unique one word identifier for the service.
          type: string
        service_name:
          description: A word or phrase naming the service.
          type: string
      required:
        - service_id
        - service_name
        - import_source_uri
      type: object
