API lerarenstage.be

lerarenstage.be API gives you programmatic access to the lerarenstage.be service, allowing you to expand and build on the lerarenstage.be platform. The possibilities are manifold and constrained only by the limits of our imaginations. Here are some of the cool applications you can build with our API:

  • Slice and dice your lerarenstage.be data in myriad ways.
  • Synchronize students and users taken on your website to lerarenstage.be.
  • Synchronize students trainings taken on your website to lerarenstage.be.
  • Use lerarenstage.be as your students training system!

Our API is based on REST principles making it super easy for you to develop and test your application.

Getting Started

After a 'pentest' we have seen that a lot of API developers are not using the API in the most secure way.
To obligate these developers to work secure we have made some changes in the core of our API.

To use our API you should have the following

  1. A valid lerarenstage.be username and password.
  2. An Application Token - apitoken in short!
  3. An Authentication Token - authtoken in short!

Application Token

If you want to use the API from lerarenstage.be you need an apitoken. You can obtain an authtoken in following ways:

  1. Contact our support team at helpdesk@lerarenstage.be

Authentication Token

All lerarenstage.be API requests require an authtoken. You can obtain an authtoken in following ways:

  1. Accessing a URL in browser
  2. Programmatically using the API

Accessing a URL in browser

If you chosen to obtain an authtoken by accessing a URL, please follow the instructions below for the live environment:

https://start.lerarenstage.be/apiauthtoken/

You will be requested to sign in if you are not signed in already.

Sample Response

  #
  #Tue Nov 30 13:08:11 PST 2010
  AUTHTOKEN=a8b6de25b5bf481824c9c4173c56231a
  RESULT=TRUE
Parameter Description
Comment Authtoken generated date.
AUTHTOKEN The temporary authtoken generated for lerarenstage.be API access.
RESULT Value is TRUE if the authtoken is generated successfully.

 

Programmatically using the API

If you chosen to obtain your authtoken via an API, please follow the instructions below:

Submit an HTTP POST request to the following URL

http://api.staging.lerarenstage-website.scalecity.space/V1/account

The body of the request should contain following mandatory fields

Parameter Description
email_id Your lerarenstage.be Email ID.
password Password for the lerarenstage.be EMAIL_ID.

Note: The parameter names passed in the POST request are case-sensitive.

The header of the request should contain following mandatory fields

Parameter Description
apitoken Your lerarenstage.be Application Token.

Note: The parameter names passed in the POST request are case-sensitive.

Sample Response

{
"code": 200
"message": "OK"
"data": {
	"date": "09/10/2016 04:04:53 pm",
	"authtoken": "B048F0A311DAEFE4E5DEAAF91E3ECA10",
	"user": {
    		"id": 51,
      		"email": "benny@vsrs.be",
       		"firstName": "Benny",
        	"lastName": "Van Vracem",
        	"phone": "+32473117111",
        	"street": "Ten Hogen",
        	"streetNumber": "125",
        	"bus": "",
        	"postcode": "9180",
        	"city": "Paaldorp",
        	"country": "Belgium",
        	"language": 1,
        	"active": 1,
		}
   }
}
Parameter Values
date Authtoken generated date.
authtoken Authtoken generated for the request.
user Authenticated user data
Important Note:

  • Generating AUTHTOKEN is as simple as a single click. You need to generate your AUTHTOKEN every time and can continue to access lerarenstage.be- API service until the token expires.

How does it work

HTTP verbs are used to access the resources GET,POST,PUT,DELETE.
All parameters in the request should be form-urlencoded.
For all the APIs you need to pass authtoken in the header request,
organization_id in the URL request
and apitoken in the header request.
Input JSON string should be passed using JSONString parameter in body.

If lerarenstage.be is able to process the request, then lerarenstage.be returns a success message wrapped in JSON format depending on the method invoked. If due to some reason lerarenstage.be is unable to process the API request, then it returns an appropriate error code and message.

Sample Error Response

  {
    code : 404,
    message: "Student does not exist."
  }

Organizations

In lerarenstage.be your business is termed as an organization. If you have multiple businesses, you simply set each of those up as an individual organization. Each organization will have its own organization id, language, students, users, etc. To sum it all up, each organization is an independent lerarenstage.be account accessible through the same credentials.

The parameter organization_id should be sent in every API request to identify the organization.

How to create an organization via API

To create an organization via API, refer the documentation link below

http://api.staging.lerarenstage-website.scalecity.space/organizations/general#create-suborganizations

How to get organization ID

To get an organization ID, send a request to the organizations GET API. The organization_id from the response JSON can be used to send as a query parameter to the API.

Parameters to be passed authtoken

Method type : GET

http://api.staging.lerarenstage-website.scalecity.space/V1/organizations

Sample Response

{
  "code": 200,
  "message": "OK",
  "organizations": [
    {
      "organization_id": "10234695",
      "name": "Zillium Inc",
      "contact_name": "John Smith",
      "email": "johnsmith@zilliuminc.com",
      "is_default_org": false,
      "plan_type": 0,
      "tax_group_enabled": true,
      "plan_name": "FREE",
      "plan_period": "",
      "language_code": "en",
      "fiscal_year_start_month": 0,
      "account_created_date": "2012-02-18",
      "account_created_date_formatted": "18 Feb 2012",
      "time_zone": "Asia/Calcutta",
      "is_org_active": true,
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "currency_symbol": "$",
      "currency_format": "###,##0.00",
      "price_precision": 2
    },
    {
      "organization_id": "10407630",
      "name": "Winston Longbridge",
      "contact_name": "John Smith",
      "email": "johnsmith@zilliuminc.com",
      "is_default_org": false,
      "plan_type": 0,
      "tax_group_enabled": true,
      "plan_name": "FREE",
      "plan_period": "",
      "language_code": "en",
      "fiscal_year_start_month": 0,
      "account_created_date": "2012-07-11",
      "account_created_date_formatted": "11 Jul 2012",
      "time_zone": "Asia/Calcutta",
      "is_org_active": true,
      "currency_id": "541000000000099",
      "currency_code": "INR",
      "currency_symbol": "Rs.",
      "currency_format": "###,##0.00",
      "price_precision": 2
    }
  ]
}

Go through the below example to see how our API works.

Say, for example, you need to create an article

Method name

http://api.staging.lerarenstage-website.scalecity.space/V1/demo/articles?organization_id=[ORGANIZATION_ID]

Method type : POST

API description : Create an demo article in your lerarenstage.be account

Parameters to be passed authtoken, organization_id ,apitoken,JSONString

Sample Request Header

http://api.staging.lerarenstage-website.scalecity.space/V1/demo/articles?organization_id=1

Sample Request Body

JSONString={
      "title": "Urbanus",
      "content": "This is a book from Urbanus"
}

Sample Response

{
    "code": 201
	"message": "Created"
	"data": {
		"id": 51
		"title": "Urbanus"
		"content": "This is a book from Urbanus"
		"active": 1
	}
}

To view list of all items

Method name

http://api.staging.lerarenstage-website.scalecity.space/V1/demo/articles?organization_id=[ORGANIZATION_ID]

Method type : GET

API description : View list of active items in your lerarenstage.be account

Parameters to be passed authtoken,apitoken,organization_id

Sample Response

{
 "code": 200,
  "message": "OK",
  "data": [
    {
      "id": 1,
      "title": "Harry Potter en de steen der wijzen",
      "content": "Harry Potter lijkt een doodgewone jongen, die sinds de dood van zijn ouders bij zijn hardvochtige oom en tante woont in de…",
      "active": 1
    },
    {
      "id": 2,
      "title": "Harry Potter en de geheime kamer",
      "content": "Na een verschrikkelijke vakantie bij zijn gemene oom en tante gaat Harry Potter naar de tweede klas van Zweinsteins Hogeschool…",
      "active": 1
    },
    {
      "id": 3,
      "title": "Harry Potter en de gevangene van Azkaban",
      "content": "Voor Harry Potter aan zijn derde jaar op Zweinsteins Hogeschool voor Hekserij en Hocus Pocus begint, moet hij de zomervakantie bij…",
      "active": 1
    }
  ],
  "page_context": {
    "total_count": 26,
    "total_pages": 2,
    "page": 1,
    "limit": 25,
    "applied_filter": "active",
    "sort_column": "title",
    "sort_order": "ASC"
  }
}

Response Format

Response will be in JSON format by default. Certain APIs support csv, html and pdf formats. Response Format can be specified in accept header or by accept paramter.

eg. accept=csv will return response as a csv file.

Each Response has code and a message.

HTTP Response Codes are listed below

200 OK
201 Created
400 Bad Request
401 Unauthorized (eg: Invalid Authtoken, ...)
403 Forbidden (eg: Write access forbidden,...)
404 Not Found
405 Method Not Allowed (Method you have called is not supported for this API)
410 Deprecated
418 I'm A Teapot (HTCPCP/1.0)
429 Rate Limit Exceeded (API usage limit exceeded)
451 Unavailable For Legal Reasons (You must agree the Privacy Disclaimer)
498 Api Token expired or invalid.
500 Internal Error
501 Not Implemented (Method you have called is not implemented)

Pagination

List API Response comes with page_context with following details,

total_count Total records
total_pages Total amount of pages
page Page number of the list
limit Number of records in the page
applied_filter Filter applied
sort_column Applied sorting
sort_order Order by which the list is sorted

Customizing the number of records to be shown in a page

lerarenstage.be provides APIs to retrieve lists of invoices, estimates and other entities. These APIs' response comes with additional information related to the list in a page_context array using which you can control how you want to receive the response.

  • For navigating through pages, use page parameter. By default first page will be listed.
  • Use the limit parameter to set the number of records you want to receive in the response.

List APIs - Some tips to filter and search your API results

lerarenstage.be API provides several ways to searching and filtering through responses of list APIs (students, users and other entities)

  1. Use the filter_by parameter to filter an API response
  2. You can search an API response using search_text parameter.
  3. We support advanced search as well. Furthermore, advanced search comes with multiple parameters. This is specific to each entity and details are available in the respective entity's API documentation.
  4. Only one of the above options would be used on the response in the following order of preference:
    • Search
    • Filter
    • Advanced Search
  5. If none of the above options are specified in a request, the response will be filtered using the default filter. This is specific to each entity and details are available in the respective entity's API documentation.
  6. You can sort your response using the sort_order parameter.
    • sort_order=ASC - Ascending
    • sort_order=DESC - Descending

Points to Note :

Date format supported for any API request is yyyy-MM-dd (2017-05-18). We do not support other formats as input.