Conscribo API

• Betreed op eigen risico: Documentatie
• https://www.conscribo.nl/api/
• https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html

Het komt erop neer dat je eerst via de API met gebruikersnaam en wachtwoord moet authenticeren met een soort van delegatie-account die toegang heeft tot het ledenbestand. Uit het authenticatie-request komt een sessionId terug, die vervolgens gebruikt moet worden als een soort van API key / cookie bij opeenvolgende requests, om informatie uit het ledenbestand op te halen of aan te passen.

Conscribo staat maximaal 3 sessies per account tegelijkertijd toe, dus voor meer gelijktijdige sessies moeten er meerdere API-accounts komen en een systeem dat het bijhouden van sessies automatiseert. Bijvoorbeeld zo. Een session ID verloopt na 30 minuten van inactiviteit.

De uiteindelijke commands zijn gewoon strings die in de JSON meegegeven worden.

Insomnia collection

Insomnia_Conscribo-20240125.json

Gebruik

1. Importeer in Insomnia / andere compatible REST API tester
2. Maak een `.env` bestand met daarin CONSCRIBO_USER=<username> en CONSCRIBO_PASS=<password>
3. Onder `Manage Environments`, pas de path aan van de twee environment variables zodat deze naar je `.env` bestand wijzen:
4. Alternatief kun je een andere environment kiezen met een interactieve prompt voor de username en password ##

API basics

JSON endpoint: https://secure.conscribo.nl/svIndicium/request.json

Request

POST request naar bovenstaande URL met:

• Twee HTTP headers (indien van toepassing):
  1. X-Conscribo-API-Version: <versienummer>
  2. X-Conscribo-SessionId: <sessionId>
• De JSON

Single command JSON

{
   "request":{
      "command":"testcommand",
      "param1":123,
      "param2":"abc"
   }
}

Multicommand JSON

Dit maal een requests object met daarin een request-lijst van commando objecten. Voeg nu ook een requestSequence toe (let op: is een string), ter identificatie van de desbetreffende request in de response.

{
   "requests":{
      "request":[
         {
            "command":"ping",
            "requestSequence":"1"
         },
         {
            "command":"thisCommandShouldNotExist",
            "requestSequence":"2"
         }
      ]
   }
}

Voorbeeld van response op bovenstaande multicommand:

{
   "results":{
      "result":[
         {
            "requestSequence":1,
            "success":1,
            "message":"pong"
         },
         {
            "requestSequence":2,
            "success":0,
            "notifications":{
               "notification":[
                  "Command not found"
               ]
            }
         }
      ]
   }
}

Authenticatie

Request

• command: "authenticateWithUserAndPass"
• userName: String(50)
• passPhrase: String(32)

{
   "request":{
      "command":"authenticateWithUserAndPass",
      "userName":"piet-test",
      "passPhrase":"V31l1gw@chtw00rd"
   }
}

Response

• success: Int, 1 of 0
• sessionId: String(40)

{
   "result":{
      "success":1,
      "sessionId":"7sg9slnsa4"
   }
}

De sessionId die hieruit komt rollen kan vanaf nu dus gebruikt worden in de X-Conscribo-SessionId header voor latere requests.

of als "success":0:

{
   "result":{
      "success":0,
      "notifications":{
         "notification":[
            "<reden hier>"
         ]
      }
   }
}