Skip to content

RESTful Interface

Jump to bottom
Till Mossakowski edited this page Jun 25, 2020 · 25 revisions

general idea

the interface

  • GET /version. Show version of hets. (example http://rest.hets.eu/version)

  • GET /filetype/coded-iri. Determine in a lightweight and fast way the file type of coded-iri. (example http://rest.hets.eu/filetype/https%3a%2f%2fontohub.org%2fhets-lib%2fBasic%2fNumbers.casl)

  • GET /dg/coded-iri/command-list?options. Output the development graph (DG) as DGXML, considering the DG commands or command line flags in command-list. The DGXML contains IRIs for the individual specs and symbols. (For HetCASL, the IRIs should be library-iri?spec-name resp. library-iri?spec-name?symbol-name but they are still simple names.) For DOL, IRIs are determined by DOL's prefixing mechanism. All the subsequent methods also use the parameters coded-iri, command-list, and option in a similar way to set up a DG.

    • Commands or flags in command-list are separated by slashes. The possible commands are those listed under "commands:" for http://rest.hets.eu/Basic/Numbers.casl
      • auto
      • glob-decomp
      • global-subsume
      • loc-decomp
      • local-infer
      • comp
      • comp-new
      • cons
      • hide-thm
      • thm-hide
      • compute-colimit
      • compute-normal-form
      • triangle-cons
      • freeness
      • importing
      • disjoint-union
      • renaming
      • hiding
      • heterogeneity
      • qualify-all-names
    • The possible flags in command-list are those from the command line. This feature may be deprecated in the future since flags can also be given as part of the query string in options (separated by "&").
      • just-structured
      • unlit
      • relative-positions
      • full-signatures
      • full-theories
      • recursive (does not make much sense)
      • (apply-automatic-rule) prefer command "auto"
      • (normal-form) prefer command "compute-normal-form"
    • The possible options are the long options from the command line (see "hets --help"). Several options are separated by ampersands. An option argument is given (as on the command line) following the equal sign (i.e. ?access-token=TOKEN). The leading two dashes of long options must be omitted in query strings. For simple options it is possible to write i.e. "full-theories=on", but "=on" should be omitted as it is not possible to switch off a flag. Not all options make sense and will be ignored or are forbidden. A particular case is "translation" that is ignored as option but used in queries for prover invocations. (The order of value pairs in query strings does not matter.)
    • from hets version 1407264924 onwards the option ?format=json is supported (example http://rest.hets.eu/dg/https%3a%2f%2fontohub.org%2fhets-lib%2fBasic%2fNumbers.casl?format=json)

  • GET /theory/coded-iri/?node=number&options. Output the theory of a node in the development graph (DG)

    • The possible options include translation=translation and format=xml, format=json, format=text or format=dol

  • GET /translations/coded-iri/command-list?options&node=iri. Get comorphisms for the node iri (or all nodes' translations, if no iri is given). We have no command to actually only translations one or all nodes yet (without proving or consistency-checking). (NOTE: The command translations was translate in previous versions of Hets)

  • GET /provers/coded-iri/command-list?options&node=iri&translation=iri. Get provers for the node iri (or all nodes' provers, if no iri is given). If translation is given, give those provers available after translation.

  • POST /prove/coded-iri/command-list is for invoking a prover on a proof goal. It accepts the following request body

    {
  "format": "json", // or "xml" or "db" //optional
  "goals": [ // required
    {
      "node": "Nat__E1", // required
      "translation": "" // the comorphism to use
      "conjecture": "ga_comm___+__", // optional, if left out, every conjecture will be proved on its own with this configuration
      "reasonerConfiguration": { // required
        "timeLimit": 10, // seconds // required
        "reasoner": "EProver" // optional
      },
      "premiseSelection": { // optional
        "kind": "manual", // or "sine" // required
        "manualPremises": ["Ax1", "Ax2"], // required if kind is "manual"
        "sineDepthLimit": 5, // optional (default: unlimited)
        "sineTolerance": 1.7, // optional (default: 1.0)
        "sinePremiseNumberLimit": 50 // optional (default: unlimited)
      },
      "useTheorems": true, // use previously proven goals as axioms // optional (default: true)
      "printDetails": true, // print details of the proof in xml/json output // optional (default: true)
      "printProof": true // print the prover output in xml/json output // optional (default: true)
    }
  ]
}

    Example call with curl:

    curl -X POST -H "Content-Type: application/json" -d '{"format": "db", "goals": [{"node": "Nat__E1", "conjecture": "ga_comm___+__", "reasonerConfiguration": {"timeLimit": 10, "reasoner": "EProver"}, "premiseSelection": {"kind": "sine", "sineDepthLimit": 2, "sineTolerance": 1, "sinePremiseNumberLimit": 50}}]}' "localhost:8000/consistency-check/$(urlencode $HETS_LIB/Basic/Numbers.casl)/auto/full-theories/full-signatures?hets-libdirs=$(urlencode $HETS_LIB)"

  • GET /consistency-checkers/coded-iri/command-list?options&node=iri&translation=iri. Get consistency checkers for the node iri (or all nodes' consistency checkers, if no iri is given). If translation is given, give those consistency checkers available after translation.

  • POST /consistency-check/coded-iri/command-list is for invoking a consistency-checker on a node. It accepts the following request body

    {
  "format": "json", // or "xml" or "db" //optional
  "goals": [ // required
    {
      "node": "Nat__E1", // required
      "reasonerConfiguration": { // required
        "timeLimit": 10, // seconds // required
        "reasoner": "darwin" // optional
      },
      "useTheorems": true, // use previously proven goals as axioms // optional (default: true)
    }
  ]
}

    Example call with curl:

    curl -X POST -H "Content-Type: application/json" -d '{"format": "db", "goals": [{"node": "Nat__E1", "reasonerConfiguration": {"timeLimit": 10}}]}' "localhost:8000/prove/$(urlencode $HETS_LIB/Basic/Numbers.casl)/auto/full-theories/full-signatures?hets-libdirs=$(urlencode $HETS_LIB)"

  • GET /folder. Return a new unique folder where an user can upload files to (see /uploadFile)

  • POST /uploadFile/codedFolder-iri/codedFileName-iri. Upload a file via POST body to one of Hets upload folder (see /folder)

    • Example call with curl:
    curl -X POST -H "Content-Type: text/plain" -d "$(cat /usr/lib/hets/hets-lib/Basic/Numbers.casl)" "localhost:8000/uploadFile/$(urlencode hetsUserFolder_4TXhXs)/$(urlencode Numbers.casl)?"
    • If you want to use the file with a prove call, encode the file t.e. /tmp/hetsUserFolder_4TXhXs/Numbers.casl

see also the old RESTful interface

Clone this wiki locally