# Zyxel Nebula API for Complit DPPSK

#### Version: Jun 29th 2020

### History
- 2020/5/12 First version.
- 2020/6/18 Added descriptions for how to create a DPPSK key and error codes.
- 2020/6/23 Update the expire time format.
- 2020/6/29 Added API to retrieve all DPPKS keys of a site.

## Introduction

Zyxel Nebula is the solution to allow IT admins to control and manage Zyxel's Nebula-enabled access points, switches and gateways, all from one place with ease.
> ***TODO*** Description for https://nebula.zyxel.com

This document describes the **APIs** that can be integrated from Complit to support DPPSK with the Nebula cloud management platform.

# Overview

- Zyxel Nebula API is RESTful and HTTPS protected.
- Zyxel Nebula API uses **API Key** instead of OAUTH2 to authenticate.
- The API scope is restricted by `Site` level because in Zyxel Nebula each site has its own Wi-Fi settings.

## RESTful API

The API endpoint is at
> https://api.nebula.zyxel.com/v1/vendor/wiflex/

Zyxel Nebula API uses JSON to exchange data thus HTTP `Content-Type` header must be `"application/json"`. Failed to provide the correct header will result HTTP `400` error.

For developing purpose please contact Zyxel for the `staging` API endpoint.

## API Key
Put the API key into the `X-ZyxelNebula-API-Key` header. If the API key fails to authenticate, HTTP `401` will be returned.

The per-site API key can be obtained on Nebula Control Center (NCC) GUI. Administrator can also revoke the API key if needed.

## Additional Response Header
In order to support debugging API usage, Zyxel Nebula API will add an additional response header `X-ZyxelNebula-API-RequestId` for tracing API. Developers should report this header to **Zyxel Nebula Developer Support** to get furthur information.

## Error
Zyxel Nebula API follows standard HTTP status code to indicate API error. For example, `200` indicates a successful API call while `404` means the resource is not found. In addition to the HTTP status code, a JSON response is always provided even if `200` is returned. The JSON example:

{ "status": 401, "message": "Authentication required.", "code": 12345, "more_info": {} }

* `message` is human-readable sentance in English. It should **not** be presented to the end-user.
* `code` is an optional field. If it exists, it indicates additional error code, which can be used for extra error processing.
* `more_info` is also optional to provide the context of error `code` for developers to debug the API integration

## Variable Notation
Some APIs take variable to either process specified resources or change the settings differently. Notation like `{{variable}}` indicates the API can be called with a variable. When used in the response, variable can be used to identify resources that are dynamic.

# API list

## SSID Information

| Verb | URL | Description | Example Response |
|------|---------------------|-----------------------|-------------------------------------------------------------------|
| GET | /dppsk/ssid | Get the SSID name | `{ "status": 200, "message:": "Ok", "body": { "ssid": "SSID" } }` |

The JSON object in the `body` is

{
    "ssid": "SSID"
}

`ssid` contains the SSID that supports DPPSK functionality. Can be used for Wi-Fi QR code.

## DPPSK Management

| Verb | URL | Description | Example Response |
|--------|--------------------|-----------------------------|----------------------------------------------------------------|
| PUT | /dppsk/key | Create/Modify a PPSK | `{ "status": 200, "message:": "Ok" }` |
| GET | /dppsk/key/{{key}} | Get the PPSK | `{ "status": 200, "message:": "Ok", "body": { ... } }` |
| DELETE | /dppsk/key/{{key}} | Delete the PPSK | `{ "status": 200, "message:": "Ok" }` |
| GET | /dppsk/keys | Get all PPSK keys | `{ "status": 200, "message:": "Ok", "body": [ {...} ]` |

PUT will either create a new PPSK if the PPSK is not existed, or modify the PPSK if the same key is existed.

The JSON object for PUT:

{
   "key": "password",
   "vlan": 1024,
   "expire": 1593561599,
   "email": "[e-mail]",
   "username": "John Doe"
}

- `expire` specifies the UTC UNIX timestamp in seconds when the key will expire. Default is `0` which means the key never exipire.
> For example `1592913600` is the timestamp equal to Tuesday, 23-Jun-20 12:00:00 UTC
- `vlan` will default to `1` if it is not specified.
- `email` and `username` are optional.

The same object will be returned in the `body` for GET a PPSK, or be in the array to return all PPSK keys. The array can be empty is no PPSK exists.
DELETE will remove the PPSK.

### Error
- `401` API key is invalid.
- `403` Need the license upgrade.
- `404` The resource is not found.
- `409` Conflit. See the `code` for details.
- `code` 40901 The size limit (total 2048 keys) is reached. The new key is added successfully but unauthorized.
- `code` 40902 E-mail is existed. The old key is updated with the new one.
- `code` 40903 The key is used by backup key.