===== polyDB REST API =====

The polyDB can be accessed via a REST API

Base path:
<code>
https://polydb.org/rest/current/
</code>

The API implements the following endpoints:
  * Info on collections
    * section
    * sections
    * collection
    * collections
  * Schema
    * schema
  * Querying the Database
    * find
    * find_one
    * count
    * distinct
    * id

Some examples are below. 

The full documentation of all endpoints with examples for data and code **[[https://polymake.org/polytopes/paffenholz/polyDB-rest.html|is here]]**.

==== Some examples for the REST API ====

=== Obtain info on available collections ===

== section ==

This returns section documentation and a list of subsections and collections in this section:
<code>
https://polydb.org/rest/current/section/<sectionname>/<subsectionname>/... 
</code>
with possible parameters <code>recursive={0,1}</code> and <code>short={0,1}</code>. Example:
<code>
https://polydb.org/rest/current/section/Polytopes?recursive=1
</code>
returns
<code>
{

    "description": "A collection of families of polytopes",
    "subsections": [
        "Polytopes.Combinatorial",
        "Polytopes.Geometric",
        "Polytopes.Lattice"
    ],
    "collections": [
        "Polytopes.Combinatorial.01Polytopes",
        "Polytopes.Combinatorial.CombinatorialTypes",
        "Polytopes.Combinatorial.FacesBirkhoffPolytope",
        "Polytopes.Combinatorial.SmallSpheresDim4",
        "Polytopes.Geometric.01Polytopes",
        "Polytopes.Lattice.01Polytopes",
        "Polytopes.Lattice.ExceptionalMaximalHollow",
        "Polytopes.Lattice.Reflexive",
        "Polytopes.Lattice.SmoothReflexive"
    ]

}
</code>

== sections ==

This returns a list of subsections of the given one

== collection ==

This prints full information on a collection. The collection is given as 
<code>
/section/<sectionname>/<subsectionname>/.../<collectionname>
</code>

Here is an example:
<code>
https://polydb.org/rest/current/collection/Tropical/SchlaefliFan
</code>

== collections ==

This lists all collections contained in a section.
<code>
/section/<sectionname>/<subsectionname>/.../
</code>

Example:
<code>
https://polydb.org/rest/current/collections/Tropical/
</code>
returns
<code>
[

    "Tropical.Cubics",
    "Tropical.Polytropes",
    "Tropical.SchlaefliFan",
    "Tropical.TOM"

]
</code>

=== Query Data ===

== find ==

This endpoint does a general query on the given collection and returns a list of the results. You can set the options sort, limit, and skip. However, the query never returns more than 10 entries.

Example:
<code>
https://polydb.org/rest/current/find/Polytopes/Lattice/Reflexive?query={"N_VERTICES"%3A5}&limit=10&skip=100
</code>
will return at most 10 reflexive polytopes with 5 vertices, skipping the first 100 matches.

== find_one ==

This works as find, but returns at most one match. The option limit does not apply here.

Example:
<code>
https://polydb.org/rest/current/find_one/Polytopes/Lattice/Reflexive?query={"N_VERTICES"%3A5}
</code>
 

== distinct ==

== count ==

This counts the number of results that match a given query. Example:
<code>
https://polydb.org/rest/current/count/Polytopes/Combinatorial/01Polytopes?query={"N_VERTICES"%3A15}
</code>
returns
<code>
139983
</code>

== id ==

Returns a single document by its id.

Example
<code>
https://polydb.org/rest/current/id/Polytopes/Combinatorial/01Polytopes/5d.15v.10f.C8
</code>


=== Obtain the JSON Schema for the data ===

== schema ==

Example
<code>
https://polydb.org/rest/current/schema/Polytopes/Lattice/Reflexive
</code>