iSAMS Rest API

[CyBeRkId2002]

I am pretty familiar with how to pull info from a batch API, but for some of the bits I need to access from our MIS (iSAMS) I need to access via REST API.  Does anyone have a quick way of explaining how this differs, and what I need to do to connect.  I am only trying to pull info, not write-back.

 

Thanks in advance.

[dhicks]

36 minutes ago, CyBeRkId2002 said:

Does anyone have a quick way of explaining how this differs, and what I need to do to connect.

 

This is the kind of thing where AI assistance can work really well, both in explaining how-it-works to you and, if you have a suitible coding agent, writing the code for you. If I remember correctly, iSAMS uses an OpenAPI/Swagger REST API interface - you might have seen other services offer the same thing, where you get a handy documentation and live try-it-out box all in one. You are basically doing HTTP(S) calls to a given endpoint, with defined parameters - the Swagger UI willl let you try out values and show you the URL strings (and even examples in Javascript / Python / etc) as you type. You authenticate via OAuth - I can't remember setting up a REST API with iSAMS, I suspect it was a while ago and I probably had to do a log-in-with-Google step in the browser the first time.

[Juba]

Hi, coming from Batch, I'd think of the change as moving from a configured extract to requests for particular resources. iSAMS describes Batch as standardised data extraction and REST as real-time access for reads and writes. You don't have to use the write operations just because they're available.

For your first test, I'd pick one small read request and check three things: the REST authentication setup for your school, the relevant GET endpoint and its filters, and whether the results are paginated. That last bit matters when you move from a successful test to an actual extract.

iSAMS also publishes its own REST example application here:
https://github.com/iSAMS/REST-API-Example-App

It's a VS2017-era example, so I'd use the current developer documentation for the exact connection details rather than assume an old sample or your Batch API credentials will carry across.

What are you using to pull the data — PowerShell, Power BI, Python, or something else — and which data are you trying to get that Batch isn't giving you? That would help narrow this down to a useful first request. No API keys or real pupil details needed.

[CyBeRkId2002]

Our main thing is a couple of bits from the medical centre (what we need is slightly less sensitive and security measures on where it will be downloaded will be tight).

 

I imagine the requests might be ok (using the Swagger guide) but I really don't understand the authentication process.  If anyone could provide a quick walkthrough on connecting (preferably via Powershell or, at a push, python) it would be really appreciated.

[Juba]

Thanks, that helps. Before writing a PowerShell example, has REST access already been configured for your script, or are you still at that initial setup stage?

Could you also say which authentication scheme/flow and field names your Swagger guide lists? Just the labels, no values. The current iSAMS developer guide requires sign-in, so I can't verify the exact request publicly and don't want to guess the connection details.

If you've already tried a request, the HTTP status and short error code would help too. Please leave out credentials, tokens and any pupil or medical data.

[dhicks]

58 minutes ago, CyBeRkId2002 said:

If anyone could provide a quick walkthrough on connecting (preferably via Powershell or, at a push, python) it would be really appreciated.

 

I have secrets (REST API keys, etc, that you get from the iSAMS Control Panel) in a simple JSON file, loadable by a script:

# Load the configuration file.
config = json.loads(dataLib.readFile("config/config.json"))
for requiredConfigParameter in requiredConfigParameters:
	if not requiredConfigParameter in config.keys():
		print("Error - required value " + requiredConfigParameter + " not set in config.json.")
		sys.exit(1)

Something like:

{
"iSAMSAPIDomain":"exampleschool.isams.cloud",
"iSAMSRESTAPIID":"12345678-1234-1234-1234-123456789012",
"iSAMSRESTAPISecret":"12345678-1234-1234-1234-123456789012",
}

Then a couple of functions to call the REST API:

# Retrive the cached iSAMS REST API Access Token, or request a new one if needed.
def authenticateWithiSAMSRESTAPI():
    if os.path.exists("accessToken.txt"):
        access_token = dataLib.readFile("accessToken.txt").strip()
    else:
        print("Authenticating with iSAMSREST API...", flush=True)
        requestURL = "https://" + config["iSAMSAPIDomain"] + "/auth/connect/token"
        response = requests.post(requestURL, data={"client_id":config["iSAMSRESTAPIID"],"client_secret":config["iSAMSRESTAPISecret"],"grant_type":"client_credentials","scope":"restapi"})
        if not response.status_code == 200:
            print("Error athenticating with the iSAMS API:")
            print("URL: " + requestURL)
            print("Error Code: " + str(response.status_code))
            print("Data: " +  str(response.content))
            sys.exit(1)
        access_token = json.loads(response.content.decode("utf8"))["access_token"]
        dataLib.writeFile("accessToken.txt", access_token)
    return access_token
iSAMSAccessToken = authenticateWithiSAMSRESTAPI()

# A handy function to do a call to the iSAMS REST API. Uses the global "iSAMSAccessToken" value for authentication - if that access token fails (default expiration is after 1 hour),
# it gets a fresh access token and tries again. Only does 2 tries to avoid getting stuck in a loop.
def iSAMSRESTAPICall(theMethod, theEndpoint, theData):
    global iSAMSAccessToken
    tries = 0
    while tries < 2:
        tries = tries + 1
        print("Doing " + theMethod + " to " + theEndpoint + " with data:", flush=True)
        print(str(theData).encode("utf-8"), flush=True)
        requestURL = "https://" + config["iSAMSAPIDomain"] + theEndpoint
        requestHeaders = {"accept":"application/json","authorization":"Bearer " + iSAMSAccessToken, "content-type":"application/json"}
        if theMethod == "get":
            response = requests.get(requestURL, data=json.dumps(theData), headers=requestHeaders)
        elif theMethod == "put":
            response = requests.put(requestURL, data=json.dumps(theData), headers=requestHeaders)
        elif theMethod == "patch":
            response = requests.patch(requestURL, data=json.dumps(theData), headers=requestHeaders)
        else:
            print("iSAMSRESTAPICall: Unknown request method: " + theMethod)
        if response.status_code == 200:
            return response
        elif response.status_code == 401 and tries < 2:
            print("iSAMSRESTAPICall: iSAMS authentication access token expired - retrying.")
            os.remove("accessToken.txt")
            iSAMSAccessToken = authenticateWithiSAMSRESTAPI()
        else:
            return response

Then you can do calls to the REST API:

getResponse = iSAMSRESTAPICall("get", "/Main/api/students/" + SchoolId, {})
    if getResponse.status_code == 200:
        pupilData = json.loads(getResponse.text)

 

[CyBeRkId2002]

Thanks very much! Think this may be a little out of my skille skill set but might take a final look over half term. 

 

I am trying to build a system that pulls team lists from Socs, collate with medical info into a table and then present to staff (maybe with Power apps). At present we can't get medical info into Socs which is a bit of a frustration for staff.