API Documentation

API Documentation

This document contains information about usage of yagcil-server API.

List of endpoints

• [/] (#---api-root) - List all available API endpoits
• [/config] (#config) - Get yagcil config
• /organization - List all organizations
• /organization/all - List all organizations for every year
• /organization/{year}{/name} - Get organization's data
• /organization/{year}{/name}/rank - Get ranking for a specified organization
• /organization/{year}{/name}/stats - Get organization stats
• /student/{name}/{year}{/org_name} - Get student's data
• /task - List all tasks
• /task/{id} - Get task's data

/ - API Root

Get links to API endpoints.

Methods allowed

• GET

URL params

none

Query params

none

Result

A dictionary of all available API endpoints.

Example

curl -X GET http://api-yagcil.rhcloud.com/

{
    "organizationListUrl": "http://api-yagcil.rhcloud.com/organization{?year}", 
    "organizationUrl": "http://api-yagcil.rhcloud.com/organization/{name}/{year}", 
    "rankUrl": "http://api-yagcil.rhcloud.com/organization/{name}/{year}/rank", 
    "taskListUrl": "http://api-yagcil.rhcloud.com/task{?org,year,limit,offset}", 
    "taskUrl": "http://api-yagcil.rhcloud.com/task/{id}"
}

/config

Get yagcil configuration - years and active year

Methods allowed

• GET

URL params

none

Query params

none

Result

Yagcil configuration

Example

curl -X GET http://api-yagcil.rhcloud.com/config

{
    "activeYear": 2014, 
    "years": [
        2014, 
        2013, 
        2012
    ]
}

/organization

List all organizations.

Methods allowed

• GET

URL params

none

Query params

param	type	default	required	description
year	int	active year (latest)	no	Year of GCI, eg., 2014, 2011

Result

A list of all organizations. If year is not set, organizations for active year are returned.

Example

curl -X GET http://api-yagcil.rhcloud.com/organization?year=2014

[
    {
        "fullName": "Apertium", 
        "name": "apertium", 
        "year": 2014
    }, 
    {
        "fullName": "BRL-CAD", 
        "name": "brlcad", 
        "year": 2014
    }, 
    {
        "fullName": "Copyleft Games", 
        "name": "copyleftgames", 
        "year": 2014
    }, 
    {
        "fullName": "Drupal", 
        "name": "drupal", 
        "year": 2014
    }, 
    {
        "fullName": "FOSSASIA", 
        "name": "fossasia", 
        "year": 2014
    }, 
    {
        "fullName": "Haiku", 
        "name": "haiku", 
        "year": 2014
    }, 
    {
        "fullName": "KDE", 
        "name": "kde", 
        "year": 2014
    }, 
    {
        "fullName": "Mifos Initiative", 
        "name": "mifos", 
        "year": 2014
    }, 
    {
        "fullName": "OpenMRS", 
        "name": "openmrs", 
        "year": 2014
    }, 
    {
        "fullName": "Sahana Software Foundation", 
        "name": "sahana", 
        "year": 2014
    }, 
    {
        "fullName": "Sugar Labs", 
        "name": "sugarlabs", 
        "year": 2014
    }, 
    {
        "fullName": "Wikimedia Foundation", 
        "name": "wikimedia", 
        "year": 2014
    }
]

/organization/all

List all organizations for every year.

Methods allowed

• GET

URL params

none

Query params

none

Result

A list of all organizations for every year.

Example

curl -X GET http://api-yagcil.rhcloud.com/organization/all

[
    {
        "year": 2014,
        "orgs": [
            {
                "fullName": "Apertium", 
                "name": "apertium", 
                "year": 2014
            }, 
            {
                "fullName": "BRL-CAD", 
                "name": "brlcad", 
                "year": 2014
            }, 
            {
                "fullName": "Copyleft Games", 
                "name": "copyleftgames", 
                "year": 2014
            }, 
            /*...*/
},
/*...*/
]

/organization/{name}/{year}

Get information about a particular organization.

Methods allowed

• GET

URL params

param	type	required	description
name	string	yes	Org's short name, for instance: sugarlabs
year	int	yes	The year which was the org in

Query params

none

Result

Organization's data

Example

curl -X GET http://api-yagcil.rhcloud.com/organization/copyleftgames/2014

{
    "fullName": "Copyleft Games", 
    "name": "copyleftgames", 
    "year": 2014
}

/organization/{year}{/name}/rank

Get ranking for a particular organization (or for the whole contest)

Methods allowed

• GET

URL params

param	type	required	description
year	int	yes	The year which was the org in
name	string	no	Org's short name, for instance: sugarlabs, if not set, ranking for the whole contest is returned

Query params

none

Result

Ranking for given organization (or the whole contest if name is not set)

Example

curl -X GET http://api-yagcil.rhcloud.com/organization/2014/rank

[
    {
        "student": "Ignacio Rodríguez", 
        "tasks": 84
    }, 
    {
        "student": "Andromeda Galaxy", 
        "tasks": 63
    }, 
    {
        "student": "AW", 
        "tasks": 61
    }
    /*...*/
]

/organization/{year}{/name}/stats

Get stats for organization (or the whole contest)

Methods allowed

• GET

URL params

param	type	required	description
year	int	yes	The year which was the org in
name	string	no	Org's short name, for instance: sugarlabs, if not set, stats for the whole contest will be returned

Query params

none

Result

Stats for organization (or the whole contest if name is not set)

Example

curl -X GET http://api-yagcil.rhcloud.com/organization/2014/stats

{
    "categories": {
        "Code": 1676, 
        "Documentation/Training": 1189, 
        "Outreach/Research": 968, 
        "Quality Assurance": 386, 
        "User Interface": 607
    }
}

/student/{name}/{year}{/org_name}

Get student's data

Methods allowed

• GET

URL params

param	type	required	description
name	string	yes	Student's name
year	int	yes	The year of GCI
org_name	string	no	Org's short name, for instance: sugarlabs. Leave empty to get results for all organizations

Query params

none

Result

Student's data (stats, tasks)

Example

curl -X GET http://api-yagcil.rhcloud.com/student/m4tx/2014

{
    "student": "m4tx",
    "stats": {
            "categories": {
                "Code": 28, 
                "Documentation/Training": 4, 
                "Quality Assurance": 2, 
                "User Interface": 4
            }
        }, 
    "tasks": [
        {
            "categories": [
                "Code"
            ], 
            "id": 4960330912366592, 
            "orgName": "wikimedia", 
            "student": "m4tx", 
            "title": "Improve the internationalisation/localisation of MediaWiki", 
            "year": 2014
        }, 
        /*...*/
    ]
}

/task

Get a list of all tasks

Methods allowed

• GET

URL params

none

Query params

param	type	default	required	description
org	string	all tasks	no	Org name to filter the results
student	string	all students	no	Student whose tasks will be returned
year	int	active year (latest)	no	Year of GCI
limit	int	no limit	no	Limit number of tasks to be fetched
offset	int	0	no	Offset to be used for infinity loading

Result

List of all tasks matching the filters.

Example

curl -X GET http://api-yagcil.rhcloud.com/task?org=copyleftgames&year=2014&limit=2&offset=11"

[
    {
        "categories": [
            "User Interface", 
            "Code"
        ], 
        "id": 4617044041400320, 
        "orgName": "copyleftgames", 
        "student": "Michal Proszek", 
        "title": "Sugar: Soy GUI", 
        "year": 2014
    }, 
    {
        "categories": [
            "Code"
        ], 
        "id": 4617877197946880, 
        "orgName": "copyleftgames", 
        "student": "Michal Proszek", 
        "title": "HGBot: IRC Flood Control", 
        "year": 2014
    }
]

/task/{id}

Get information about a praticular task

Methods allowed

• GET

URL Params

param	required	description
id	yes	Id of the task

Query params

none

Result

Task's data.

Example

curl -X GET http://api-yagcil.rhcloud.com/task/4617044041400320

{
    "categories": [
        "User Interface", 
        "Code"
    ], 
    "id": 4617044041400320, 
    "orgName": "copyleftgames", 
    "student": "Michal Proszek", 
    "title": "Sugar: Soy GUI", 
    "year": 2014
}