Skillhive Developers

Swarms

Get swarm data through the Skillhive API

List All Swarms

Endpoint: /api/swarm/

Method Action Parameters
GET List swarms
  • Offset: int fetch skills starting from (optional, default: 0)
  • Limit: int how many skills to get (optional, default: 20, limit 0-50)

An example of a return response:

{
  "limit":20,
  "offset":0,
  "previous":null,
  "next":"/api/swarm/?offset=20&limit=20",
  "total_count":124,
  "collection": [
    {
      "id":67521,
      "uri":"/api/swarm/67521/",
      "title":"Testing Project",
      "type":"project",
      "description":"This is a testing project.",
      "is_official":false,
      "is_draft":false,
      "location":"Helsinki, Finland",
      "competence": 78,     // The current user's competence...
      "interest": 90,       // ...and interest for this swarm.
      "resources":{
        "users":"/api/swarm/67521/user/",
        "skills":"/api/swarm/67521/skill/"
      },
      "start_at"::
      "end_at":
      "duration":6,
      "created_at" :
      "updated_at" :
    },
    ...
  ]
}

Fetch a Single Swarm

Endpoint: /api/swarm/:swarm_id/

Fetch a single swarm based on swarm id.

Method Action Parameters
GET Get swarm details N/A

An example of a return response:

{
  "id":67521,
  "uri":"/api/swarm/67521/",
  "title":"Testing Project",
  "type":"project",
  "description":"This is a testing project.",
  "is_official":false,
  "is_draft":false,
  "location":"Helsinki, Finland",
  "resources":{
    "users":"/api/swarm/67521/user/",
    "skills":"/api/swarm/67521/skill/"
  },
  "start_at":
  "end_at":
  "duration":8,
  "created_at" :
  "updated_at" :
}

Create a Swarm

Endpoint: /api/swarm/

Create a new swarm.

Method Action
POST Create a new swarm

Possible post parameters:

Parameter Type Default Values Optional
type string idea idea, problem, project, message, survey, announcement, objective, onboarding, course, certificate, role, expert true
title string Max length 255 characters false
description string true
status string in_progress in_progress, completed true
is_draft boolean false true
is_official boolean false true
access string public public, members true
start_at string now() true
end_at string now() true
location string true
show_map boolean false true
duration string Max length 32 characters true
price string Max length 32 characters true
participants_min integer true
participants_max integer true
skills string A comma separated list of skill names: JavaScript, C++, Node.js true

Notice that almost all values have some sensible defaults and actually the swarm title is the only required parameter you need to send. Notice also, that not all of the swarm attributes are actually used in all swarm types. For instance, the number of allowed participants defined by participants_min and participants_max parameters are only used for course swarms. The values are saved but they won't be shown to users in the Skillhive UI.

If the swarm is created succesfully, the return response will be similar to the single swarm listing you get through the api.

Fetch Skills in Swarm

Endpoint: /api/swarm/:swarm_id/skill/

Fetch skills used in swarm.

Method Action Parameters
GET Get swarm skills
  • Offset: int fetch skills starting from (optional, default: 0)
  • Limit: int how many skills to get (optional, default: 20, limit 0-50)

An example of a return response:

{
  "limit":20,
  "offset":0,
  "previous":null,
  "next":"/api/swarm/67521/skill/?offset=20&limit=20",
  "total_count":8,
  "collection": [
    {
      "id":8989,
      "uri":"/api/swarm/67521/skill/8989/"
      "name":"PHP",
      "competence":75,
      "is_mandatory":true,
      "created_at":
      "updated_at":
    },
    {
      "id":8990,
      "uri":"/api/swarm/67521/skill/8990/"
      "name":"Unit testing",
      "competence":65,
      "is_mandatory":false,
      "created_at":
      "updated_at":
    },
    ...
  ]
}

Endpoint: /api/swarm/:swarm_id/skill/:skill_id/

Get a single swarm skill by skill_id.

Method Action Parameters
GET Get a single swarm skill N/A

An example of a return response:

{
  "id":8989,
  "uri":"/api/swarm/67521/skill/8989/"
  "name":"PHP",
  "competence":75,
  "is_mandatory":true,
  "created_at":
  "updated_at":
}

Swarm Statistics

Endpoints to get swarm statistics.

Swarm Skill Statistics

Endpoint: /api/swarm/:swarm_id/statistics/skills/

Get statistics about swarm members' skills in the skills that are tagged in the swarm.

Method Action Parameters
GET Get skill statistics N/A

An example of a return response:

{
  "total_count":3, // Total number of skills in this swarm
  "collection": [
    {
      "name":"Scrum",
      "uri":"/api/skill/?skill=Scrum",
      "competence_avg": 65,
      "interest_avg": 78,
      "expert_count": 8, // How many users in this swarm has this skill
      "users":[
        {
          "id":765,             
          "uri":"/api/user/765/",
          "name":"User Name",
          "icon_url":"https://company.skillhive.com/user/765/icon",
          "competence": 97,
          "interest": 78
        },
        {
          "id":768,             
          "uri":"/api/user/768/",
          "name":"Jane Doe",
          "icon_url":"https://company.skillhive.com/user/768/icon",
          "competence": 88,
          "interest": 95
        }
      ]
    },
    {
      "name":"Node.js",
      "uri":"/api/skill/?skill=node.js",
      "competence_avg": 45,
      "interest_avg": 89,
      "expert_count": 4, // How many users in this swarm has this skill
      "users":{
        {
          "id":768,             
          "uri":"/api/user/768/",
          "name":"Jane Doe",
          "icon_url":"https://company.skillhive.com/user/768/icon",
          "competence": 72,
          "interest": 81
        },
        {
          "id":765,             
          "uri":"/api/user/765/",
          "name":"User Name",
          "icon_url":"https://company.skillhive.com/user/765/icon",
          "competence": 56,
          "interest": 43
        }
      }        
    },
    ...
  ]
}