SciNote API integration ELN and LIMS 2019

RESTful API and Why Is It Good for Your Lab? – VIDEO

5 min read, 3 min video

With the latest SciNote upgrade, we’ve released the first version of the RESTful API for SciNote. In this article, I’d like to explain what an API actually means – for those who are not familiar with the technicalities of it – and why it is really good to have one in 2019.

RESTful API (application program interface) is, very broadly, a mechanism that allows 3rd party applications used in the laboratory (e.g. LIMS systems, management systems, CRM, ERP systems, …) to access SciNote data (and vice-versa) in a standardized, structured, documented and secured manner. RESTful APIs nowadays are one of the key concepts behind software integrations, interfacing and interoperability.

 

Not a Premium user yet? See how you can start using API integrations: Get a Quote

 

Introduction

I’d like to start this article by going back into the past for a while. If you’ve been born in the 80s or early 90s, like me, there’s a chance you might still remember what the earlier web pages used to look like. Back then, nobody was talking about web applications. Web was pretty much a gigantic repository of so-called “static” web pages, where each individual web page was identified by a unique identifier that you typed into your browser bar – an URL! Each web page was comprised of lots of text, some basic styling and formatting (some tables, colors, images), and some hyperlinks to other web pages. That was it! No animations, fancy user interactions, etc. You might remember the Bob Dole/Jack Kemp presidential campaign website, Netscape home page, or similar web pages that were popular in the 90s.

To summarize, web used to look like something along these lines. It’s really remarkable how far we’ve come since then!

Coincidentally, a RESTful API looks very similar to this. A RESTful API is a set of defined URLs that users (or, more often, computers) can query, to retrieve, modify, or create data. The big difference is that on the web site, a lot of things are going on that relate to the way we humans perceive information. There are text paragraphs, titles, colors, different fonts and font sizes, alignments, and so forth. More often than not, these things are not actually part of the data itself, but merely add to the presentation of the data. Since computers don’t really care about visual representation, but only about the data, these things can easily be omitted, and as a result, RESTful API only deals with data, and metadata (data about data… confusing, right!?).

Examples for tech-savvy readers

An example of two RESTful API URLs within SciNote are the following:

GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/users

The first URL will, upon being requested by a program/script/user/browser/…, return all the projects within the team with the given team ID, and the results should look something along these lines (I’ve omitted some metadata for clarification):

[
  {
    "id": "1",
    "type": "projects",
    "attributes": {
      "name": "My initial project",
      "visibility": "hidden",
      "start_date": null,
      "archived": false
    }
  },
  {
    "id": "2",
    "type": "projects",
    "attributes": {
      "name": "My second project",
      "visibility": "hidden",
      "start_date": null,
      "archived": false
    }
  }
]

While the second URL could, for example, return a single user-project association that is the sole user on the given project (with the given project ID), e.g.:

[
  {
    "id": "1",
    "type": "user_projects",
    "attributes": {
      "role": "owner"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "1",
          "type": "users"
        }
      }
    }
  }
]

As you can see, there is no coloring, paragraphs, etc., only some basic formatting. This is because – as I mentioned – a RESTful API is all about the data, and not the visual representation of it. Most of the time, RESTful API deals with textual data, but there are methods to handle various other formats such as images, videos, etc., as well. It all boils down to ones and zeroes in the end, right?

If you check the examples above, there is a certain basic structure in the way the data is formatted. SciNote RESTful API uses a very popular data format called JSON (JavaScript object notation), which is a lightweight specification of how to format text data, and various relationships between data objects (e.g. key-value pairs and lists).

If you imagine, the list of various URLs that comprise a RESTful API can quickly grow large:

GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/users
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/users/<USER_ID>
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/activities
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/comments
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/comments/<COMMENT_ID>
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/experiments/<EXPERIMENT_ID>/connections
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/experiments/<EXPERIMENT_ID>/tasks
GET https://<server-name>/api/v1/teams/<TEAM_ID>/projects/<PROJECT_ID>/experiments/<EXPERIMENT_ID>/tasks/<TASK_ID>/users

...

That is why the RESTful API documentation is also very important, and is a critical part of any good API. The documentation is meant for any person that aims to either access the API directly, or plans to write a piece of software/computer code that will use the API to integrate with SciNote. The documentation lists all the details about the URLs, what outputs individual requests return, what is the data format/structure, authentication/authorization, enumeration, and so forth.

Check out SciNote Premium Academia and Industry PlansSee Plans

Why is it good?

Imagine a RESTful API in this way: it’s a documented, well-defined and computer-friendly layer that can be used to securely access SciNote data (read, update, modify it) based on your lab’s needs.

It gives an organization (or an individual), with adequate technical
computer programming knowledge, a very powerful tool to either:

  • automate various things within SciNote
  • push or modify data into SciNote
  • export data from SciNote
  • and potentially integrate all this with any 3rd party application/program/system used in the lab

You could, for example, keep in sync all your inventories in SciNote with the data located within your 3rd party sample/reagents/labware management software, e.g. a LIMS system.

Or simply export various data from SciNote locally into a folder on your computer. Or into your Dropbox folder! Or push your local files on your computer into SciNote.

The possibilities are, quite frankly, limitless!

We at SciNote Team hope that the provided SciNote RESTful API will help you while setting up the systems in your lab!

For business related, integration and similar inquiries please contact:

By Luka Murn, Principal Software Engineer at SciNote LLC

Leave us a comment: