Semiocast API tutorial
Introduction

About this tutorial

This tutorial will get you through all the steps from the registration, getting your certificate, testing and using the Semiocast API.

You should be familiar with the cURL command line tool to run the examples below.

Formating conventions

The following formating conventions are used through out the documentation. Inputs in the tutorial are formated as follows:

This is what you type

And outputs as follows:

This is an output
Inputs and outputs are usually one-liners, but they may be formatted one several lines for better readying:
This is a an input formated on several lines for better reading but it you copy-paste it, it should paste a one line only

Getting started

In order to use the Semiocast API, you must first register to the Semiocast API developer program. Registration is free. You can register here.

Download your Certificate

All access to the Semiocast API methods are done with a certificate. You can download you certificate from your account page.

Certificates are available in two formats: PEM and PKCS-12.

Curl examples in this tutorial use the PEM format certificate. Be sure to download the PEM format certificate before proceeding, you will need it to test Semiocast API with curl.

Verify your certificate

Semiocast API provides 2 API methods to test your certificate and parameters formating.

Now that you have your certificate, verify that you can connect to the Semiocast API server by calling the test/null API method. This method does not return anything, it is only intended to test your certificate.

Use the following line to test your certificate, replace PASSWORD with your account password:

curl -E semiocast-api.pem:PASSWORD https://api.semiocast.com/1/test/null.json

Be sure to use https and not plain http.

Querying this URL does not return anything, it is only intended to test the certificate only:

  • If curl returns without any error and without displaying any message, everything is OK: Your certificate is valid and you can connect to Semiocast API.
  • If curl returns the following message:
    curl: (58) unable to set private key file: 'semiocast-api.pem' type PEM
    Your password may be incorrect. If you can log in with the same password, download again the PEM certificate and try again. If it fails, contact us.
  • If curl returns the following message:
    curl: (58) unable to use client certificate (no key found or wrong pass phrase?)
    You may have used the PKCS-12 certificate or your certificate is corrupted. Download again the PEM certificate and try again. If it fails, contact us.

Passing parameters

Now you will verify that Semiocast API is able to parse your data with the following line:

curl -E semiocast-api.pem:PASSWORD "https://api.semiocast.com/1/test/echo.json?foo=bar&data=Test%20Echo"

You should get the following result in JSON format:

{"method":"test","params":{"foo":"bar","data":"Test Echo"}}

The test/echo call returns the method called (test) and each parameter associated to its value.

Return formats

Semiocast API methods support 2 formats for returning results: JSON and XML. Getting a result in one format is just a matter of specifying the extension in the API method call.

Replace the extension json by the extension xml in previous example:

curl -E semiocast-api.pem:PASSWORD "https://api.semiocast.com/1/test/echo.xml?foo=bar&data=Test%20Echo"

And you will get the following result in XML:

<?xml version="1.0" encoding="UTF-8"?> <echo> <method>test</method> <params> <foo>bar</foo> <data>Test Echo</data> </params> </echo>

Hint: a more convenient way to use curl to access Semiocast API consists to send parameters thanks to the -d option:

curl -E semiocast-api.pem:PASSWORD -d foo=bar -d data='Test Echo' "https://api.semiocast.com/1/test/echo.json"

will return:

{"method":"test","params":{"foo":"bar","data":"Test Echo"}}