# Usage

## API Access

|          |                                       |
| -------- | ------------------------------------- |
| Headers  | `Authorization: Bearer <api_key>`     |
| Endpoint | `https://app.eduflow.com/api/graphql` |

General requests to the API endpoint will return JSON.

The response will be wrapped in `"data"` and match the shape of the original query.

{% tabs %}
{% tab title="curl" %}
[curl(1)](https://curl.haxx.se/) example:

```javascript
EDUFLOW_API_KEY=<api_key> \
  curl \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${EDUFLOW_API_KEY}" \
  -X POST \
  -d '{"query": "{institution {name}}"}' \
  https://app.eduflow.com/api/graphql
```

{% endtab %}

{% tab title="wget" %}
[wget(1)](https://www.gnu.org/software/wget/) example:

```javascript
EDUFLOW_API_KEY=<api_key> \
 wget -qO- \
 --header 'Content-Type: application/json' \
 --header "Authorization: Bearer ${EDUFLOW_API_KEY}" \
 -X POST \
 --post-data '{"query": "{institution {name}}"}' \
 https://app.eduflow.com/api/graphql
```

{% endtab %}

{% tab title="node" %}

```javascript
#!/bin/env node

if (!process.env.EDUFLOW_API_KEY) {
  console.error(`Enter your EDUFLOW_API_KEY:

  env EDUFLOW_API_KEY=<api_key> node index.js`);
  return;
}

const http =
  process.env.EDUFLOW_API_PROTOCOL === "http"
    ? require("http")
    : require("https");

const query = JSON.stringify({
  query: `{
    institution {
      name
    }
  }`,
});

const options = {
  hostname: process.env.EDUFLOW_API_HOSTNAME || "app.eduflow.com",
  path: "/api/graphql",
  port: process.env.EDUFLOW_API_PORT || 443,
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Content-Length": query.length,
    Authorization: "Bearer " + process.env.EDUFLOW_API_KEY,
    "User-Agent": "Node",
  },
};

const req = http.request(options, (res) => {
  let data = "";
  res.on("data", (d) => {
    data += d;
  });
  res.on("end", () => {
    console.log(JSON.parse(data).data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(query);
req.end();
```

{% endtab %}

{% tab title="python" %}

```python
#!/bin/env python
import json
import os
import sys
import urllib.request

api_key = os.getenv("EDUFLOW_API_KEY")
if api_key is None:
    sys.exit(
        """Enter your EDUFLOW_API_KEY:

    env EDUFLOW_API_KEY=<api_key> python app.py"""
    )

query = """{
  institution {
    name
  }
}"""

raw_data = {
    "query": query,
    "variables": {},
}
data = json.dumps(raw_data).encode("utf-8")

options = {
    "data": data,
    "headers": {
        "Content-Type": "application/json",
        "Content-Length": len(data),
        "Authorization": f"Bearer {api_key}",
        "User-Agent": "Node",
    },
}

hostname = os.getenv("EDUFLOW_API_HOSTNAME", "app.eduflow.com")
protocol = os.getenv("EDUFLOW_API_PROTOCOL", "https")
port = os.getenv("EDUFLOW_API_PORT", 443)
url = f"{protocol}://{hostname}:{port}/api/graphql"

request = urllib.request.Request(url, **options)

try:
    response = urllib.request.urlopen(request)
    print(response.read().decode())
except urllib.error.HTTPError as e:
    print(e.read().decode())
```

{% endtab %}
{% endtabs %}

Response:

```javascript
{"data":{"institution":{"name":"Test institution"}}}
```

## Session-based / GraphiQL

Institution administrators that are logged into Eduflow can access the API endpoint and query through the graphql interface.

When logged in, go directly to <https://app.eduflow.com/api/graphql>

![Hovering over an object will show an introspection tooltip, typing will show autocompletion hints](https://2518674650-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3GmK_EkZyQQJhTJyLh%2F-MRzvVlW_aNdLdO5tFe_%2F-MRzvw-WLh7vAfolbVmN%2Fgraphiql-hover-and-completion.gif?alt=media\&token=bf55d3ad-d308-482f-bad4-b35e88a528ae)

![GraphiQL has a searchable documentation available on the sidebar](https://2518674650-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3GmK_EkZyQQJhTJyLh%2F-MRzwW8qImzkVYf-zhN3%2F-MRzwZGQa36N6u66knEe%2Fgraphiql-docs.gif?alt=media\&token=4885fbb2-56b8-40c5-96b9-20830d024ad4)

If you access via browser, the GraphQL endpoint will show [GraphiQL](https://github.com/graphql/graphiql)

To open GraphiQL's sidebar, mouseover an object in the query and click an object inside a tooltip, or clicking "Doc":

![This is found on the top right of GraphiQL if the sidebar is closed.](https://2518674650-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M3GmK_EkZyQQJhTJyLh%2F-MSFIWCUT96ZXEROhs2w%2F-MSFJDpddkkKJ2YTqey1%2Fimage.png?alt=media\&token=ae2b70f6-96e0-4ce3-81b4-5e9cccd73891)

GraphiQL works with both session-based (logged into app.eduflow\.com) and by passing authorization headers.