# API

The API allows for integration of our services in your application and is available
at [https://igsn.uni-kiel.de/api/](https://igsn.uni-kiel.de/api/).

## Access types

Each user has an API access type.

Access type | Description
----------- | -----------
*None* | The user can not access the API.
*Default* | This is the default API access type. The user can access the default API routes.
*Extended* | The user can access the default and extended API routes.

## API keys

If you want to use the API, you'll need to create an API key first. Here's how you
can do it:

1. Click on your username.
2. Select *My profile* from the dropdown list.
3. In your profile settings, look for the option to create API keys.
4. Click the *Create API key* button to generate your API key.

![Create API key form](../_static/api_keys_create.png)

## Routes

### Default

:::{note}
{octicon}`lock;1em;sd-text-info` To access the default routes, the user needs to
have *default* or *extended* API access.
:::

#### Registration requests

Type | Route | Description
---- | ----- | -----------
GET | [/api/registration_requests](https://igsn.uni-kiel.de/api/registration_requests) | Retrieves the collection of *RegistrationRequest* resources.
POST | [/api/registration_requests](https://igsn.uni-kiel.de/api/registration_requests) | Creates a *RegistrationRequest* resource.
GET | [/api/registration_requests/{id}](https://igsn.uni-kiel.de/api/registration_requests/{id}) | Retrieves a *RegistrationRequest* resource.
PUT | [/api/registration_requests/{id}](https://igsn.uni-kiel.de/api/registration_requests/{id}) | Replaces the *RegistrationRequest* resource.

:::{note}
Please note that you can only access your own registration requests.
:::

#### Repositories

Type | Route | Description
---- | ----- | -----------
GET | [/api/repositories](https://igsn.uni-kiel.de/api/repositories) | Retrieves the collection of *Repository* resources.
GET | [/api/repositories/{prefix}](https://igsn.uni-kiel.de/api/repositories/{prefix}) | Retrieves a *Repository* resource.

#### DOI

Type | Route | Description
---- | ----- | -----------
GET | [/api/dois](https://igsn.uni-kiel.de/api/dois) | Returns a list of DOIs.
GET | [/api/dois/{id}](https://igsn.uni-kiel.de/api/dois/{id}) | Retrieves a DOI resource.

:::{note}
Please note that these routes are mirrored to the DataCite API and you can only access
DOIs that are stored in repositories that you have read access to.
:::

### Extended

:::{note}
{octicon}`lock;1em;sd-text-info` To access the extended routes, the user needs to
have *extended* API access.
:::

#### DOI

Type | Route | Description
---- | ----- | -----------
POST | [/api/dois](https://igsn.uni-kiel.de/api/dois) | Creates a DOI resource.
PUT | [/api/dois/{id}](https://igsn.uni-kiel.de/api/dois/{id}) | Replaces the Doi resource.

:::{note}
Please note that these routes are mirrored to the DataCite API and you can only create
or update DOIs that are stored in repositories that you have write access to.
:::

## Examples

### Retrieve the collection of your registration requests

```console
curl -X 'GET' \
  'https://igsn.uni-kiel.de/api/registration_requests' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'
```

### Retrieve a collection of all repositories

```console
curl -X 'GET' \
  'https://igsn.uni-kiel.de/api/repositories' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'
```

### Retrieve a repository by prefix

```console
curl -X 'GET' \
  'https://igsn.uni-kiel.de/api/repositories/<prefix>' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your-api-key>'
```

### Create a registration request

```console
curl -X 'POST' \
  'https://igsn.uni-kiel.de/api/registration_requests' \
  -H 'accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "title": "My title",
    "notes": "some notes",
    "repository": "/api/repositories/<prefix>",
    "data": [
      <your-registration-data>
    ]
  }'
```