API

From 44Net Wiki
Revision as of 18:50, 15 October 2024 by W6JMK (talk | contribs) (document error handling)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The AMPRNet Portal has an associated API that allows the data and functionality of the Portal to be accessed programatically.

Version 1

Version 1 of the API uses a RESTful design, accessible only via SSL (https://) to increase security.

All requests to the API require the client to authenticate by using Basic HTTP authentication, so you will need a username and password in order to access any part of the API, this can be obtained by registering for an account on the Portal.

Once you have an account, you can create your API Key (password) from the "Profile' menu link, in the "Security" section. The API username is the same username you used to login to the Portal via your web browser.

Version 2

Version 2 of the API also uses a RESTful design. Requests and responses are exchanged via HTTPS. Access is controlled using Bearer authorization. So, each request must include an HTTP header like this:

Authorization: Bearer <API Token>

To obtain an API token, register with the Portal, log in, browse your profile and copy the value of "API Token".

Some responses are in JSON format. Requests should include a header:

Accept: application/json

To get complete current routing information in JSON, request https://portal.ampr.org/api/v2/encap/routes. For example, a Unix command like this will output complete current routing information:

curl -s -H "Authorization: Bearer $APItoken" -H "Accept: application/json" https://portal.ampr.org/api/v2/encap/routes

The response includes a serial number, which changes when any route is updated. To get the current serial number (but not the routes) in JSON, request https://portal.ampr.org/api/v2/encap/serial.

If something goes wrong, the HTTP response may include an HTTP status code other than 200 and/or an error message in the body. For example, a request with an invalid API token will elicit a response including:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message":"Unauthenticated."}