Trying the BioID Web Service REST API with cURL
Let's try to do some hands-on REST with the BioID Web Service (BWS). You'll need to already have requested a trial instance. Then you can go to the BWS Management portal and register a client app. I did this and got an email telling me that it runs on storage
bws with in partition
9184. After having created it I can see that it appears in the “Client Apps” tab with the identifier
115243460.9184.app.bioid.com. The app name is something you can choose yourself when registering a new one.
One last thing we need to get started is the password for accessing the BWS. You can get it by clicking on the edit button if you did not write it down initially. There, you can also request a new password—which is what I will do before posting this article.
For me, it spells
Give me a token
Now we're all set and as a first thing, point your browser of choice to https://bws.bioid.com/extension/token?id=115243460.9184.app.bioid.com&bcid=bws.9184.42. You see that the assigned partition appears twice, once as the subdomain and once in the BCID-Parameter.
The BCID (Biometric Class ID) should be unique for every user. We'd normally spell it
bws/9184/42, but for the REST service also accepts
bws.9184.42, as forward slashes might look confusing. The BCID consists of the storage (bws), the partition (9184) and the user who we are inquiring about. This last part can be chosen freely. But beware that giving the same ID to several users or giving returning users new IDs basically sabotages everything.
What the browser displays is a plain-text string that—in my case—looks like this:
This is your token that you'll need to do further inquiries about that user. We can also use the command line to get it. Assuming you have cURL installed, this will download the token to a text file:
Next, let's see if we already enrolled face images (we could also ask for voice) for user 42:
May I introduce…
After that, uploading is easy:
I shortened the token part, because it's really long, but you have to put all of it working. For both images I got the answer
After that, we tell the web service that these two files should be enrolled for the user 42. We don't have to specify the BCID again, because all this is encoded in the token.
Again, I get no error, which means that we have successfully enrolled our first user!
For a quick check:
gives a HTTP 200, which is what we expect. After getting a new token with
task=verify (the old one invalidated anyway after one use) we can upload a third image of the same face and see if it is recognized.
All commands succeed and I'm happy.