Metadata-Version: 2.4
Name: allianceauth-restapi
Version: 1.0.0
Summary: Example plugin app for Alliance Auth.
Author-email: munsking <aa-rest-api@munsking.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
License-File: LICENSE
Requires-Dist: allianceauth>=5
Requires-Dist: coverage ; extra == "test"
Requires-Dist: factory_boy ; extra == "test"
Requires-Dist: allianceauth-app-utils>=1.32 ; extra == "test"
Project-URL: Changelog, https://forgejo.munsking.com/munsking/allianceauth-restapi/src/branch/master/CHANGELOG.md
Project-URL: Documentation, https://forgejo.munsking.com/munsking/allianceauth-restapi/
Project-URL: Homepage, https://forgejo.munsking.com/munsking/allianceauth-restapi
Project-URL: Source, https://forgejo.munsking.com/munsking/allianceauth-restapi
Project-URL: Tracker, https://forgejo.munsking.com/munsking/allianceauth-restapi/issues
Provides-Extra: test

# REST API plugin app for Alliance Auth

Alliance auth plugin to open up REST API endpoints

Currently supports:
- [structuretimers](https://github.com/AllianceAuth-Apps/aa-structuretimers)

## Installation

### Step 1 - Check Preconditions

Please make sure you meet all preconditions before proceeding:

1. Restapi is a plugin for [Alliance Auth](https://gitlab.com/allianceauth/allianceauth). If you don't have Alliance Auth running already, please install it first before proceeding. (see the official [AA installation guide](https://allianceauth.readthedocs.io/en/latest/installation/auth/allianceauth/) for details)

2. To use the Structure Timers endpoints you need to have the plugin installed, [installation instructions](https://github.com/AllianceAuth-Apps/aa-structuretimers#installation)

Note that Structure Timers is compatible with Alliance Auth's Structure Timer app and can be installed in parallel.

### Step 2 - Install app

Make sure you are in the virtual environment (venv) of your Alliance Auth installation. Then install the newest release from PyPI:

```bash
pip install allianceauth-restapi
```

### Step 3 - Configure settings

Configure your Auth settings (`local.py`) as follows:

- Add `'restapi'` to `INSTALLED_APPS`
- add `'restapi'` to `APPS_WITH_PUBLIC_VIEWS`

### Step 4 - Finalize installation

Run migrations & copy static files

```bash
python manage.py migrate
```

Restart your supervisor services for Auth

## How to use

Create a apikey in the admin area of your auth instance.

The api key will have the same rights as the user it's assigned to.

In your request headers, `X-restapi-Key` is one of your created api keys.

The following endpoints are available:

- `/rest/api/structuretimers`
  - `GET` gives you a list of active structure timers, filtered via header params:
    - `hours-passed`: timers that have been passed by X hours (default: 2)
    - `hours-until`: timers coming out in X hours (default: 24)
  - `POST` let's you create a new timer with json data in the request body:
  -
    ``` JSON
    {
        "system": "Jita", # [string] Name of the system
        "structure": 35834, # [int] ID of the structure type
        "structure_name": "TEST TEST TEST", # [string] name of the structure
        "timer": "2026.07.20 01:19:20", # [string] eve online formatted date-time
        "timertype": "AN", # [string] type code of the timer¹
        "objective": "HO", # [string] type code of objective/standings¹
        "msg":"this is just a test timer", # [string] detail note
        "opsec": true # [boolean] is this timer opsec (optional, default: false)
    }
    ```

1: [type codes](https://github.com/AllianceAuth-Apps/aa-structuretimers/blob/master/structuretimers/models.py#L281)

## examples

### create a new timer

```bash
curl -s -H "X-restapi-Key:this_is_my_api_key" -X POST https://auth.my-eve-corp.com/rest/api/structuretimers -d \
'
{
        "system": "Jita",
        "structure": 35834,
        "structure_name": "TEST TEST TEST",
        "timer": "2026.07.20 01:19:20",
        "timertype": "AN",
        "objective": "HO",
        "msg":"this is just a test timer",
        "opsec": true
    }
' | jq
```

result:

```JSON
{
  "username": "munsking",
  "system": {
    "id": 30000142,
    "name": "Jita"
  },
  "structure": {
    "id": 35834,
    "type": "Keepstar",
    "name": "TEST TEST TEST"
  },
  "url": "http://auth.my-eve-corp.com/structuretimers/edit/1"
}
```

### get a list of active timers

``` bash
curl -s -H "X-restapi-Key:this_is_my_api_key" -H "hours-passed:12" -H "hours-until:48" -X GET https://auth.my-eve-corp.com/rest/api/structuretimers | jq

```

result:

``` JSON
{
  "timers": [
    {
      "date": "2026-07-20 01:19",
      "timestamp": 1784510360,
      "structure": {
        "id": 35834,
        "name": "TEST TEST TEST",
        "type": "Keepstar"
      },
      "stance": "HO",
      "owner": null,
      "type": "AN",
      "system": "Jita",
      "important": false,
      "opsec": true
    }
  ]
}
```

