Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • archive
  • lifecycles
  • chat
  • 20180621-revision
  • 20180621-before_revision
6 results
Blame Permalink
apidocs.md 27.53 KiB

API Documentation

Implements API for IT4I SCS Information System.

  • api revision: 9eb0678f / 2017-12-08 11:06:12 +0100
  • api version: 0.9-11-g9eb0678
  • apidoc building date: 2017-12-11 13:13:08 +0100

Summary

Resource Operation Description
account-expire GET /api/v1/account-expire/(login) Account expiration date
accounts-to-close GET /api/v1/accounts-to-close/(category) Standard accounts close to expiration date
check-access POST /api/v1/check-access Access check to queue
dedicated-time GET /api/v1/dedicated-time/(cluster_type) HPC dedicated time
graph_affiliation_stats GET /api/v1/graph_affiliation_stats Graph affiliation statistics
graph_research_area_stats GET /api/v1/graph_research_area_stats Graph research area statistics
graph_utilization_stats GET /api/v1/graph_utilization_stats Graph utilization statistics
irregular-accounts-to-close GET /api/v1/irregular-accounts-to-close Special accounts close to expiration date
it4ifree POST /api/v1/it4ifree/(login) Free account resources
it4ifreetoken GET /api/v1/it4ifreetoken/(login) Free account token
motd GET /api/v1/motd/(category) SCS messages of the day
ping GET /api/v1/ping Connection test
quota-extra GET /api/v1/quota-extra User extra quota
version GET /api/v1/version API version

API Details

GET /api/v1/account-expire/(login) Access to this service is restricted to just few source ipv4 addresses.

It returns the account expiration date. The account may participates on several projects. If all projects were already finished, there will come a time when the account expires as well. It will happen after:

  • 365 days - for all standard accounts
  • 31 days - for special (e.g. training) accounts

Query Parameters:

 

  • login – account id

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/account-expire/chr0139

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "login": "chr0139",
    "projectendtime": "2019-07-25 21:59:59"
  }
]

GET /api/v1/accounts-to-close/(category) Access to this service is restricted to just few source ipv4 addresses.

The standard account expires 365 days after the date when the last project was finished. This service returns the list of standard accounts which are close to the expiration date. The closeness time interval depends on requested parameter.

Query Parameters:

 

  • first – 93±2 days before expiration date
  • second – 31±2 days before expiration date
  • third – 7±2 days before expiration date

Response JSON Object:

 

  • fullname (string) – user full name
  • login (string) – account id
  • projectendtime (string) – project end date
  • userclosetime (string) – project end date shifted by 272/334/358 days

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/accounts-to-close/second

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "fullname": "Smith John",
    "login": "johnsm",
    "projectendtime": "2017-01-08 22:59:59",
    "userclosetime": "2017-11-09 22:59:59"
  }
]

POST /api/v1/check-access A service to check if account and/or related project has the access to specified queue.

Request JSON Object:

 

  • login (string) – account id
  • queue (string) – queue id
  • pid (string) – project id, not required if querying projectless queue

Status Codes:

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"pid":"DD-13-5","login":"johnsm","queue":"qfat"}' \
  https://scs.it4i.cz/api/v1/check-access

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  "OK Access granted for regular queue."

GET /api/v1/dedicated-time/(cluster_type) Returns list of times dedicated for HPC maintainance. It is not possible to use HPC services during maintainance.

Query Parameters:

 

  • all – returns all dedicated times for all clusters
  • salomon – returns all times just for salomon cluster
  • anselm – returns all times just for anselm cluster
  • active – returns dedicated times for all clusters which are now active
  • planned – returns dedicated times for all clusters which are now active or scheduled in the future

Status Codes:

Example request:

curl -i curl https://scs.it4i.cz/api/v1/dedicated-time/all

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "cluster_type": "salomon",
    "dateEfficiency": "2017-11-21 09:45:00",
    "dateExpiration": "2017-11-21 23:59:00",
    "updated_at": "2017-11-21 09:45:00"
  }
]

GET /api/v1/graph_affiliation_stats Access to this service is restricted to just few source ipv4 addresses.

It returns graph data useful to plot statistics of using HPC by some affiliations.

Query Parameters:

 

  • height – optional, graph height in pixels, default 300
  • width – optional, graph width in pixels, default 420
  • sizepct – optional, graph size in percents, default 40

Status Codes:

Example request:

curl -i -X GET --data height=50 -d sizepct=50 \
  -G https://scs.it4i.cz/api/v1/graph_affiliation_stats

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"
  {
    chart: {
      plotBackgroundColor: null,
      plotBorderWidth: null,
      plotShadow: false,
      height: 50,
      width: 420,
    },
    credits: {
      text: 'IT4Innovations 2017-11-14 13:21'
    },
    title: {
      text: ''
    },
    exporting: {
      enabled: false
    },
    tooltip: {
      pointFormat: '{point.percentage:.1f} %'
    },
    plotOptions: {
      pie: {
        allowPointSelect: true,
        cursor: 'pointer',
        size: '50%',
        startAngle: 315,
        dataLabels: {
          enabled: true,
          format: '{point.name}',
        }
      }
    },
    series: [
      {
        type: 'pie',
        data: [
          ['IT4Innovations', 143320459.886 ],
          ['Akademie věd ČR', 67329442.8672 ],
          ['CEITEC', 41987818.0711 ],
          ['Masarykova univerzita', 22767491.1453 ],
          ['VUT Brno', 18184662.5402 ],
          ['Univerzita Karlova', 15544836.8455 ],
          ['ČVUT', 12383341.426 ],
          ['Matematicko-fyzikální fakulta', 4583152.32333 ],
          ['Uppsala University', 4562701.04 ],
          ['Others', 36525837.5894 ],
        ]
      }
    ]
  }
"

GET /api/v1/graph_research_area_stats Access to this service is restricted to just few source ipv4 addresses.

It returns graph data useful to plot statistics of using HPC by various science fields.

Query Parameters:

 

  • height – optional, graph height in pixels, default 300
  • width – optional, graph width in pixels, default 420
  • sizepct – optional, graph size in percents, default 40

Status Codes:

Example request:

curl -i -X GET -G https://scs.it4i.cz/api/v1/graph_research_area_stats

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"
  {
    chart: {
      plotBackgroundColor: null,
      plotBorderWidth: null,
      plotShadow: false,
      height: 300,
      width: 420,
    },
    credits: {
      text: 'IT4Innovations 2017-11-14 13:43'
    },
    title: {
      text: ''
    },
    exporting: {
      enabled: false
    },
    tooltip: {
      pointFormat: '{point.percentage:.1f} %'
    },
    plotOptions: {
      pie: {
        allowPointSelect: true,
        cursor: 'pointer',
        size: '40%',
        startAngle: 315,
        dataLabels: {
          enabled: true,
          format: '{point.name}',
        }
      }
    },
    series: [
      {
        type: 'pie',
        data: [
          ['Materials Science ', 205656805 ],
          ['Bio Sciences ', 65319185 ],
          ['Plasma & Particle Physics ', 21935334 ],
          ['Service', 20537970 ],
          ['Engineering ', 15691906 ],
          ['Informatics', 12335969 ],
          ['Applied Mathematics', 9458711 ],
          ['Earth Sciences ', 8804183 ],
          ['Astro Sciences ', 4229242 ],
          ['Other Research Areas', 2493851 ],
        ]
      }
    ]
  }
"

GET /api/v1/graph_utilization_stats Access to this service is restricted to just few source ipv4 addresses.

It returns graph data to plot statistics of HPC week utilization during last 100 days.

Query Parameters:

 

  • height – optional, graph height in pixels, default 300
  • width – optional, graph width in pixels, default 420
  • sizepct – optional, graph size in percents, default 40

Status Codes:

Example request:

curl -i -X GET -G https://scs.it4i.cz/api/v1/graph_utilization_stats

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"
  {
    chart: {
      zoomType: 'x',
      plotBorderWidth: 0,
      borderWidth: 0,
      borderRadius: 0,
      borderColor: '#DDDDDD',
      height: 300,
      width: 420
    },
    series: [
      {
        name: 'Cores utilized',
        type: 'areaspline',
        data: [
          [ Date.UTC(2017,7,6), 18466],
          [ Date.UTC(2017,7,7), 18606],
          [ Date.UTC(2017,7,8), 19075],
          [ Date.UTC(2017,7,9), 19962],
          [ Date.UTC(2017,7,10), 20239],
          [ Date.UTC(2017,7,11), 20425],
          [ Date.UTC(2017,7,12), 20110],
          [ Date.UTC(2017,7,13), 19413],
          [ Date.UTC(2017,7,14), 20204],
          [ Date.UTC(2017,7,15), 20058],
          [ Date.UTC(2017,7,16), 19890],
          [ Date.UTC(2017,7,17), 18102],
          [ Date.UTC(2017,7,18), 18529],
          [ Date.UTC(2017,7,19), 18871],
          [ Date.UTC(2017,7,20), 18704],
          [ Date.UTC(2017,7,21), 17106],
          [ Date.UTC(2017,7,22), 17854],
          [ Date.UTC(2017,7,23), 19541],
          [ Date.UTC(2017,7,24), 19691],
          [ Date.UTC(2017,7,25), 19335],
          [ Date.UTC(2017,7,26), 20776],
          [ Date.UTC(2017,7,27), 20856],
          [ Date.UTC(2017,7,28), 21116],
          [ Date.UTC(2017,7,29), 21705],
          [ Date.UTC(2017,7,30), 17907],
          [ Date.UTC(2017,7,31), 18085],
          [ Date.UTC(2017,8,1), 18564],
          [ Date.UTC(2017,8,2), 17449],
          [ Date.UTC(2017,8,3), 17472],
          [ Date.UTC(2017,8,4), 17173],
          [ Date.UTC(2017,8,5), 14445],
          [ Date.UTC(2017,8,6), 17952],
          [ Date.UTC(2017,8,7), 18813],
          [ Date.UTC(2017,8,8), 17847],
          [ Date.UTC(2017,8,9), 16434],
          [ Date.UTC(2017,8,10), 14957],
          [ Date.UTC(2017,8,11), 15695],
          [ Date.UTC(2017,8,12), 15495],
          [ Date.UTC(2017,8,13), 11848],
          [ Date.UTC(2017,8,14), 9612],
          [ Date.UTC(2017,8,15), 9765],
          [ Date.UTC(2017,8,16), 11730],
          [ Date.UTC(2017,8,17), 12932],
          [ Date.UTC(2017,8,18), 12296],
          [ Date.UTC(2017,8,19), 11230],
        ],
        color: '#AA4643'
      }
    ],
    title: {
      text: ''
    },
    credits: {
      text: 'IT4Innovations 2017-11-14 14:14'
    },
    exporting: {
      enabled: false
    },
    plotOptions: {
      areaspline: {
        fillOpacity: 0.5
      },
      pie: {
        dataLabels: {
          enabled: false
        },
        showInLegend: true
      },
      series: {
        turboThreshold: 0
      },
      line: {
        marker: {
          enabled: false
        }
      }
    },
    xAxis: {
      type: 'datetime',
      title: {
        text: 'Date',
        style: {
          color: '#000000'
        }
      }
    },
    yAxis: {
      min: 0,
      tickInterval: 1000,
      title: {
        text: 'Cores [-]',
        style: {
          color: '#000000'
        }
      }
    },
  }
"

GET /api/v1/irregular-accounts-to-close Access to this service is restricted to just few source ipv4 addresses.

The special (e.g. training) account expires 31 days after the date when the last project was finished. This service returns the list of special accounts which are already after this the expiration date.

Response JSON Object:

 

  • login (string) – account id
  • projectendtime (string) – project end date

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/irregular-accounts-to-close

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "login": "dd-01",
    "projectendtime": "2009-09-19 23:59:59"
  }
]

POST /api/v1/it4ifree/(login) A service to check resources of the projects on which the account participate. If the calculation run on 1 cpu core during 1 hour, it consumes 1 core-hour from the project resources. However, some calculations (or their placement) can be cheaper. Actual consumed core-hours are reduced by a cheaping factor and then deduct from the project resources. See https://docs.it4i.cz/salomon/resources-allocation-policy/#normalized-core-hours-nch for more details about so-called normalized core-hours. The json response contains two parts:

  • me – data from projects, where the account has access
  • me_as_pi – data from projects, where the account is PI (primary investigator)

Request JSON Object:

 

  • login (string) – account id
  • it4ifreetoken (string) – token

Response JSON Object:

 

  • login (string) – account id
  • pid (string) – project id
  • pi_login (string) – account id which is PI
  • days_left (string) – days to the end of project, --- if project is inactive or not yet started
  • free (int) – free core-hours which can be still consumed
  • total (int) – total core-hours assigned to the project
  • used (int) – actual consumed core-hours
  • used_with_factor (int) – consumed normalized core-hours
  • used_by_me (int) – core-hours consumed by the account
  • used_by_me_with_factor (int) – normalized core-hours consumed by the account
  • corehours (int) – core-hours consumed by the account
  • core_hours_with_factor (int) – normalized core-hours consumed by the account

Status Codes:

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"login":"johnsm", "it4ifreetoken": "abc"}' \
  https://scs.it4i.cz/api/v1/it4ifree/johnsm

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "me": [
    {
      "days_left": "---",
      "free": 17124,
      "login": "johnsm",
      "pid": "DD-13-6",
      "total": 100000,
      "used": 82876,
      "used_by_me": 0,
      "used_by_me_with_factor": 0,
      "used_with_factor":82876
    },
    {
      "days_left": "---",
      "free": 0,
      "login": "johnsm",
      "pid": "DD-14-12",
      "total": 1000,
      "used": 8641,
      "used_by_me": 0,
      "used_by_me_with_factor": 0,
      "used_with_factor": 8641
    }
  ],
  "me_as_pi": [
    {
      "core_hours": 82876,
      "core_hours_with_factor": 82876,
      "login":"abc",
      "pi_login": "johnsm",
      "pid": "DD-13-6"
    },
    {
      "core_hours": 0,
      "core_hours_with_factor": 0,
      "login": "johnsm",
      "pi_login": "johnsm",
      "pid":"DD-13-6"
    }
  ]
}

GET /api/v1/it4ifreetoken/(login) Access to this service is restricted to just few source ipv4 addresses.

It returns free token for the account.

Query Parameters:

 

  • login – account id

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/it4ifreetoken/johnsm

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "it4ifreetoken": "abc"
}

GET /api/v1/motd/(category) Returns SCS messages of the day.

Query Parameters:

 

  • notice – returns only notice messages
  • important – returns only important messages
  • all – returns all messages

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/motd/notice

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "author": "svi47",
    "category": "notice",
    "created_at": "2017-10-12 11:44:51",
    "dateEfficiency": "2017-10-12 11:41:00",
    "dateExpiration": "2017-11-28 14:30:00",
    "dateModification": "2017-10-12 13:44:51",
    "deleted_at": null,
    "id": 169,
    "messageBody": "For more information about the course,
      please visit its web page: https://goo.gl/cvFsFH",
    "state": null,
    "title": "Invitation to the Course Productivity Tools
      for High Performance Computing (2017-11-27 to 2017-11-28)",
    "typeMotd": null,
    "updated_at": "2017-10-12 11:44:51"
  }
]

GET /api/v1/ping A service for testing connection to API.

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/ping

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "message": "pong"
}

GET /api/v1/quota-extra Access to this service is restricted to just few source ipv4 addresses.

Returns all accounts which have active filesystem quotas bigger than standard.

Response JSON Object:

 

  • login (string) – account id
  • system_name (string) – computer system name
  • filesystem (string) – folder name
  • quota_gb (int) – disk usage quota for in GB
  • quota_ki (int) – quota for number of files in thousands
  • expiration (string) – expiration date
  • description (string) – reason for allocation extra quotas

Status Codes:

Example request:

curl -i curl https://scs.it4i.cz/api/v1/quota-extra

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "login": "johnsm",
    "system_name": "anselm",
    "filesystem": "HOME",
    "quota_gb": 500,
    "quota_ki": 1500,
    "expiration": "2017-12-31",
    "description": "build SW"

  }
]

GET /api/v1/version Returns basic information about API.

Status Codes:

Example request:

curl -i https://scs.it4i.cz/api/v1/version

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "hostname": "scs.it4i.cz",
   "revision": "ceac8aa / 2017-11-01 12:25:27 +0100",
   "version": "0.8.2-34-gceac8aa"
}

©2017, IT4Innovations. | Powered by Sphinx 1.5.6 & Alabaster 0.7.10