List All Swarms
Endpoint: /api/swarm/
Method | Action | Parameters |
---|---|---|
GET | List swarms |
|
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 |
|
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
}
}
},
...
]
}