Using AlternC's REST(ish) API

🕓 Jul 27, 2016
🏷️
  • #debian
  • #linux
  • #alternc

    • I recently wanted to try and use AlternC’s API to see how it worked in the hope that some tasks could become more automated with external clients.

    In AlternC 3.1-3.5 there are two sections of the github repo which deal with the api, first of the panel api index, which documents how you are supposed to make the calls; and the API service objects.

    The essence of the API interface is that you call the API service objects by name in your requests, and given that there seems to be no more broadly written documentation the only way to know what objects are available and what parameters (optional and required) are needed is to go through the service object code nd pull out all the relevant information yourself.

    Authentication

    AlternC currently supports two different authentication methods: login & sharedsecret.

    Login

    In both 3.1 and 3.5 stable branches this patently does not work, as the the database object they are using is not properly instantiated. An issue should be filed (and patch + request could be made as well).

    The format for calling this is:

    GET https://panel.example.com/api/auth/login?login=USERNAME&password=PASSWORD

    Note: The response here also generates a 500 Internal server error. In addition to not properly initializing the database connection variable, the exception handler fails to properly access the “code” property of the exception and PHP bails out.

    Shared Secret

    This method actually works, but as of AlternC 3.3 (on debian jessie), there doesn’t appear to be a way in the interface to add shared secrets for accounts. I first added one in the database

    insert into sharedsecret (uid, secret) values (UID, 'SECRETMUSTBE32CHARACTERSLONG');

    Note: the shared secret must be 32 characters long, alpha-numeric characters only (both upper and lower case are accepted).

    Example request:

    GET https://panel.example.com/api/auth/sharedsecret?secret=MYSECRET

    Response

    In the event of a successful connection, a json object is sent with the following attributes:

    • uid: the integer uid of the user
    • isAdmin: true/false
    • token: string, token to use in future requests.

    Token Validity

    Tokens generated through the auth appear to valid for 1 month following their creation by default. Additionally, repeated auth requests generate new tokens and do not invalidate previously existing tokens. Client code using this API should probably then store the token generated and use it until an authentification failure occurs.

    Other requests

    There are few formats available for making requests:

    • “post”
      • GET /api/post?token=X&object=Y&action=Z&…
      • POST /api/post # keys as above, but json object in post data
    • “rest”
      • GET /api/rest/object/action?token=X&…
      • POST /api/rest/object/action # keys as above but json object in post data

    My goal here isn’t to create AlternC API documentation, but serve as a starting point for those who would like to use it. The objects can be found through browsing the code, and the actions are generally methods of those API objects. The parameters for each aren’t particularly documented in the method docblock, so you have to read the function to determine which are required, optional, and when given what format the paramters must conform to.

    Example request (Creating an account):

    GET https://panel.example.com/api/rest/account/add?token=TOKEN&login=test&pass=test&nom=Test&prenom=Test2&mail=test@alternc.local

    Response (failure):

    {
    "code": 111202
    "message": "[admin] This login already exists"
    "content": null
    "metadata": null
}

    In a successful account creation request, the uid of the created account is stored in the “content” of the returned object.

    See Also