// to display images directly on GitHub
ifdef::env-github[]
:encoding: UTF-8
:lang: en
:doctype: book
:toc: left
:imagesdir: ../images
endif::[]

////

    This file is part of the PacketFence project.

    See PacketFence_Developers_Guide.asciidoc
    for authors, copyright and license information.

////

//== HTTP JSON API


PacketFence provides an HTTP JSON API which exposes most of its functionality. 

The full API specification for:

* the latest stable release is available from: https://packetfence.org/doc/api/
* the latest devel release is available from: https://packetfence.org/doc/api-devel/

The API is exposed on 127.0.0.1 (localhost) as well as the management interface of the server for remote calls.
Users access the API on TCP port 9999 over a secure connection (HTTPS).

Authentication can be done using either the webservices credentials or any credentials that are valid on the web admin interface.

=== How to use the API

==== On a PacketFence server

The [command]`pfperl-api` command located in [filename]`/usr/local/pf/sbin/`
directory can be use directly from a PacketFence server to query the API without having to specify an authentication token
and extra-parameters.

Example to get your general configuration:

[source,bash]
----
/usr/local/pf/sbin/pfperl-api get /api/v1/config/base/general \
| python -m json.tool
----

Example to create a node:

[source,bash]
----
/usr/local/pf/sbin/pfperl-api get -M POST /api/v1/nodes/ \
-c '{"mac":"22:33:44:55:66:77","pid":"default"}' \
| python -m json.tool
----

Example to create a node with JSON payload in a dedicated file:

.example.json
[source,json]
----
{"mac":"22:33:44:55:66:77","pid":"default"}
----

[source,bash]
----
cat example.json | \
/usr/local/pf/sbin/pfperl-api get -M POST /api/v1/nodes/ \
| python -m json.tool
----


==== On a different computer

NOTE: The API specification mentionned above provides ready-to-use curl commands through the "Try it out" button.

First, get an authentication token with the webservices credentials or an admin account:

[source,bash]
----
curl -X POST "https://PF_MANAGEMENT_IP:9999/api/v1/login" \
-H  "accept: application/json" \
-H  "Content-Type: application/json" \
-d "{\"username\":\"admin\",\"password\":\"admin\"}" \
--insecure |
python -m json.tool
----

You will get following response :

[source,json]
----
 {
    "token": "MY_TOKEN"
 }
----

Then use this token to query the API. The following example fetches the general configuration:

[source,bash]
----
curl -X GET "https://PF_MANAGEMENT_IP:9999/api/v1/config/base/general" \
-H  "accept: application/json" \
-H  "Authorization: MY_TOKEN" \
--insecure |
python -m json.tool
----

Although the API should mostly stay the same, backward compatibility is not 100% guaranteed for the moment until the v1 API reaches full maturity.
