Introduction

Welcome to Sengab API !
Currently, we use only HTTP illustrating examples for the documentation.

Entities

This demonstrates project entities.

User

Parameter	Type	Description	Example
id	Number	Generated by the server.
url	String	URL for User object.
first_name	String	User’s first name.
last_name	String	User’s last name.
gender	String	User’s gender.	"gender": "M"
image	String	User profile picture.
about	Object	Holds email and bio short description of the user.	"about":{ "Email":"ali@allam.com", "bio":null }
stats	Object	Count of created projects and contributions of user.	"stats":{ "projects":0, "contributions":5 }
projects	String	URL for created projects by the user.	http://api.sengab.com/v1/users/user::14/created_projects
contributions	String	URL for the user contributions.	http://api.sengab.com/v1/users/user::14/contributions
created_at	String	Profile created date.	We Use ISO 8601 format.

Project

Parameter	Type	Description	Example
id	Number	IDs are generated by the Server.
url	String	URL for project.
name	String	Project name.
image	String	Project photo.
owner	Object	Project creator, contains the User id, url, first_name and last_name	"owner":{ "id":11, "url":"http://api.sengab.com/v1/users/11", "first_name":"Galileo", "last_name":"Galileo" }
goal	Number	Project contributions count goal, when to declare the project as completed.
template_body	Object	Project content.	"template_body":{ "image_title":"Take a photo of your pet."}
created_at	String	Project creation date.	We Use ISO 8601 format.
enrollments_count	Number	Count of enrolled users.
contributions_count	Number	Count of contributions.
category	Object	Indicates the project category, contains id,url,and name	"category":{ "id":210, "url":"http://api.sengab.com/v1/categories/210", "name":"social" }
template_id	Number	Project Template.
brief_description	String	Short project description.
detailed_description	String	Detailed project description.
results	String	URL for project results.
stats	String	URL for project statistics.

Category

Parameter	Type	Description	Example
id	Number	Generated by the Server.
url	String	URL for category.
name	String	Category name.
image	String	Category photo.
description	String	Description of the category.

Contribution

Parameter	Type	Description	Example
id	Number	Generated by the Server.
url	String	URL of the contribution.
project	Object		"project":{ "id":1, "url":"http://api.sengab.com/v1/projects/1", "name":"Say what you see", "image":"http://www.sengab.com/projects_images/1.jpg" }
contributor	Object		"user":{ "id":12, "url":"http://api.sengab.com/v1/users/12", "first_name":"Emma", "last_name":"Watson", "image":"http://www.sengab.com/projects_images/12.jpg" }
created_at	String		Generated by the client.
data	Object	Content of data will be different according to the project template.	"data":{ "first_name": "Emma", "last_name": "Watson" }

Projects

List all projects

GET /projects HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this:

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "project::3",
    "name": "Project of template 3",
    "owner": {
      "id": "user::11",
      "url": "http://api.sengab.com/v1/users/user::11",
      "name": "Ahmad El-Melegy",
      "image": "https://lh3.googleusercontent.com/.../photo.jpg"
    },
    "url": "http://api.sengab.com/v1/projects/project::3",
    "goal": 2000,
    "image": "image",
    "template_id": 3,
    "created_at": "2016-02-12T03:21:55Z",
    "brief_description": "short",
    "enrollments_count": 0,
    "contributions_count": 17,
    "category": {
      "category_id": "category::3",
      "url": "http://api.sengab.com/v1/categories/category::3",
      "name": "sports"
    }
  },
  {
    "id": "project::2",
    "name": "Project of template 2",
    "owner": {
      "id": "user::11",
      "url": "http://api.sengab.com/v1/users/user::11",
      "name": "Ahmad El-Melegy",
      "image": "https://lh3.googleusercontent.com/.../photo.jpg"
    },
    "url": "http://api.sengab.com/v1/projects/project::2",
    "goal": 2000,
    "image": "image",
    "template_id": 2,
    "created_at": "2016-02-12T03:21:55Z",
    "brief_description": "short",
    "enrollments_count": 0,
    "contributions_count": 3,
    "category": {
      "category_id": "category::2",
      "url": "http://api.sengab.com/v1/categories/category::2",
      "name": "sports"
    }
  },
  {
    "id": "project::1",
    "name": "Project of template 1",
    "owner": {
      "id": "user::11",
      "url": "http://api.sengab.com/v1/users/user::11",
      "name": "Ahmad El-Melegy",
      "image": "https://lh3.googleusercontent.com/.../photo.jpg"
    },
    "url": "http://api.sengab.com/v1/projects/project::1",
    "goal": 2000,
    "image": "image",
    "template_id": 1,
    "created_at": "2016-02-12T03:21:55Z",
    "brief_description": "short",
    "enrollments_count": -2,
    "contributions_count": 3,
    "category": {
      "category_id": "category::1",
      "url": "http://api.sengab.com/v1/categories/category::1",
      "name": "health"
    }
  }
]

This endpoint retrieves all projects.

HTTP Request

GET http://api.sengab.com/v1/projects

Optional Parameters

Parameter	Type	Value
filter	string	popular / latest

Get a specific project

GET /projects/:id HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this:

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

{
    "id": 7,
    "url": "http://api.sengab.com/v1/projects/7",
    "name": "Show me a pet",
    "image": "http://www.sengab.com/projects_images/7.jpg",
    "owner": {
        "id": 41,
        "url": "http://api.sengab.com/v1/users/41",
        "first_name": "Albert",
        "last_name": "Einstein",
        "image": "http://www.sengab.com/profiles_images/41.jpg"
    },
    "created_at": "2008-01-14T04:33:35Z",
    "brief_description": "This a brief description about this project",
    "detailed_description": "This is a detailed description about this project",
    "enrollments_count": 1730,
    "contributions_count": 1542,
    "template_id": 1,
    "category": {
        "id": 584,
        "url": "http://api.sengab.com/v1/categories/584",
        "name": "science"
    },
    "description": "Take a photo for any pet you",
    "results": "http://api.sengab.com/v1/projects/7/results",
    "stats": "http://api.sengab.com/v1/projects/7/stats"
}

This endpoint retrieves a specific project.

HTTP Request

GET http://api.sengab.com/v1/projects/<PROJECT_ID>

Get a project with template body

GET /projects/:id?format="with_template_body" HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this:

HTTP/1.1 206 Partial Content
Content-Type: application/json

{
  "id": "project::3",
  "name": "Project of template 3",
  "owner": {
    "id": "user::11",
    "url": "http://api.sengab.com/v1/users/user::11",
    "name": "Ahmad El-Melegy",
    "image": "https://lh3.googleusercontent.com/../photo.jpg"
  },
  "url": "http://api.sengab.com/v1/projects/project::3",
  "goal": 2000,
  "image": "image",
  "template_id": 3,
  "template_body": {
    "questions": [
      {
        "id": "1",
        "title": "what?"
      },
      {
        "id": "2",
        "title": "why?"
      }
    ]
  },
  "created_at": "2016-02-12T03:21:55Z",
  "brief_description": "short",
  "detailed_description": "detailed one",
  "enrollments_count": 25,
  "contributions_count": 17,
  "category": {
    "category_id": "category::3",
    "url": "http://api.sengab.com/v1/categories/category::3",
    "name": "sports"
  },
  "results": "result::3",
  "stats": "stats::3"
}

This endpoint retrieves a specific project with the template body.

HTTP Request

GET http://api.sengab.com/v1/projects/<PROJECT_ID>?format="with_template_body"

Required Parameter

Parameter	Type	Value
format	string	with_template_body

Add project

POST /projects HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: X-Auth-Token YOUR_ACCESS_TOKEN

{
    "name": "Recognize image",
    "brief_description": "short",
    "detailed_description": "long",
    "goal": 500,
    "image": "fdfdfdfdfjdkfd4f5dfdf4df",
    "created_at": "2016-02-12T03:21:55Z",
    "category_id": "category::5",
    "template_id": 1,
    "template_body": {}
}

This endpoint adds a new project.

HTTP Request

POST http://api.sengab.com/v1/projects

Request body

Parameter	Description
name	Project name
brief_description	Short project description.
detailed_description	Detailed project description.
goal	Project contributions count goal.
image	Project image.
created_at	Project creation date.
category_id	Id of project’s category.
template_id	Defines the project template, for more check Templates section.
template_body	Defines the template body for a project. It differs according to template_id, for more check Templates section.

The above command returns JSON structured like this

HTTP/1.1 201 CREATED
Content-Type: application/json

{
    "id": 4545454,
    "url": "http://www.sengab.com/projects/45454",
    "name": "Recognize Image",
    "image": "http://www.sengab.com/projects_thumbnails/15454545.jpg",
    "created_at": "2016-02-12T03:21:55Z"
}

Search in projects

GET /projects/search/recognize HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "project::2",
    "name": "Project of template 2",
    "owner": {
      "id": "user::11",
      "url": "http://api.sengab.com/v1/users/user::11",
      "name": "Ahmad El-Melegy",
      "image": "https://lh3.googleusercontent.com/.../photo.jpg"
    },
    "url": "http://api.sengab.com/v1/projects/project::2",
    "goal": 2000,
    "image": "image",
    "template_id": 2,
    "created_at": "2016-02-12T03:21:55Z",
    "brief_description": "short",
    "enrollments_count": 7,
    "contributions_count": 3,
    "category": {
      "category_id": "category::2",
      "url": "http://api.sengab.com/v1/categories/category::2",
      "name": "sports"
    }
  }
]

This endpoint retrieves projects with titles including the value of the search query parameter.

HTTP Request

GET http://api.sengab.com/v1/projects/search/<keyword>

URL Parameters

Parameter	Description
keyword	The keyword that you search for in projects’ titles.

List stats of a project

GET /projects/<PROJECT_ID>/stats HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

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

{
    "goal": 900,
    "contributions_count": 721,
    "contributors_count": 685,
    "contributors_gender": {
        "males": 358,
        "females": 227,
        "unknown": 100
        }
}

This endpoint retrieves statistics of a project.

HTTP Request

GET http://api.sengab.com/v1/projects/<PROJECT_ID>/stats

Response body

Parameter	Description
goal	Project contributions count goal.
contributions_count	Contributions count of the project.
contributors_count	Contributors count of the project.
contributors_gender	Object of contributors gender.
contributors_gender.males	Male contributors count.
contributors_gender.females	Female contributors count.
contributors_gender.unknown	Unknown contributors count.

List results of a project

GET /projects/<PROJECT_ID>/results HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns various JSON structured, based on the project type

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

{
    "contributions_count":2210,
    "results":""
}

"results" field differs according to the project template

This endpoint retrieves results of a project.

HTTP Request

GET http://api.sengab.com/v1/projects/<PROJECT_ID>/results

Templates

Currently, we provide 6 static templates for projects, we will illustrate their structure through the following examples.

Template 1 : Y/N question with geolocation

Add project

{
  "template_id":1,
  "template_body":{
    "question_title":"Are you happy today?"
  }
}

Submit contribution

{  
  "data":{  
    "location":{  
      "lat":-33.8709434,
      "lng":151.1903114
    },
    "answer":"yes"
  }
}

List results of project

{  
  "results":{  
    "yes":[  
      {  
        "lat":-33.86755700000001,
        "lng":151.201527
      },
      {  
        "lat":-33.86755700000001,
        "lng":151.201527
      }
    ],
    "no":[  
      {  
        "lat":-33.86755700000001,
        "lng":151.201527
      },
      {  
        "lat":-33.86755700000001,
        "lng":151.201527
      }
    ]
  }
}

DESCRIPTION

In this template the Location will not be shown to the user in the project as a question, but it will be sent implicitly alongside his response to the yes/no question.

The result of this project will be shown as a map with two types of markers indicating the answer to the question in this location. So we will need to return all location contributions as a single result.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.question_title	String	Defines the question.

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
location	Object	Holds the value of the location (longitude/latitude).	YES
location.lat	Number	Holds the value of latitude.	YES
location.lng	Number	Holds the value of longitude.	YES
answer	String	Holds contributor’s answer to the question	YES

LIST RESULTS OF PROJECT

results object, holds processed location data.

Parameter	Type	Description
yes	Array	Lists all location contributions with answer yes
no	Array	Lists all location contributions with answer no

Template 2 : Image collector

Add project

{  
  "template_id":2,
  "template_body":{  
    "image_title":"Take a photo of your pet."
  }
}

Submit contribution

{  
  "data":{  
    "image":"R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
    "caption":"My cat lily"
  }
}

List results of project

{  
  "results":[  
    {  
      "image_url":"http://www.sengab.com/projects_uploads/56842.jpg",
      "caption":"My cat lily"
    },
    {  
      "image_url":"http://www.sengab.com/projects_uploads/41242.jpg",
      "caption":"Dory, my fish"
    }
  ]
}

DESCRIPTION

In this template, the project owner wants to collect images with a specific description.

The result of this project will be shown as a photo grid with the caption of each photo.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.image_title	String	Defines the description of required image.

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
image	String	Base64 value of the image.	YES
caption	String	Contributor’s description of his image.	YES

LIST RESULTS OF PROJECT

results array, holds images’ URLs and captions.

Parameter	Type	Description
image_url	String	Contribution image URL.
caption	String	Contributor’s description of his submitted image.

Template 3 : Survey

Add Project

{  
  "template_id":3,
  "template_body":{  
    "questions":[  
      {  
        "title":"You are a teenager ?"
      },
      {  
        "title":"Do you think you are social ?"
      }
    ]
  }
}

Submit contribution

{  
  "data":{  
    "answers":[  
      {  
        "id":1,
        "ans":"yes"
      },
      {  
        "id":2,
        "ans":"no"
      }
    ]
  }
}

List results for project

{  
  "results":[  
    {  
      "id":1,
      "title":"You are a teenager ?",
      "contributions_count":454,
      "yes_count":400,
      "no_count":54
    },
    {  
      "id":2,
      "title":"Do you think you are social ?",
      "contributions_count":454,
      "yes_count":100,
      "no_count":354
    }
  ]
}

DESCRIPTION

In this template, the project owner wants to conduct a survey about a specific topic.

The results of this project will be displayed as a chart for each question showing the percentage of yes and no answers to the question.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.questions	Array[Object]	Defines the questions of the survey.
template_body.questions.id	Number	ID of the question.
template_body.questions.title	String	Title of the question.

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
answers	Array	Holds IDs of questions and values of their answers(yes/no).	YES
answers.id	Number	ID of the question.	YES
answers.ans	String	Answer of the question.	YES

LIST RESULTS OF PROJECT

results array of objects, each has the following fields.

Parameter	Type	Description	Required
id	Number	Question ID.	YES
title	text	Question Title.	YES
contributions_count	Number	count of contributions of question	YES
yes_count	Number	holds number of yes answers to question.	YES
no_count	Number	holds number of no answers to question.	YES

Template 4 : Image collector with geolocation

Add Project :

{
  "template_id":4,
  "template_body":{
    "image_title":"Take a photo of road accidents you witness"
  }
}

Add Contribution :

{
  "data":{
    "image":"R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
    "caption":"Accident in Tahrir Square",
    "location":{
      "lat":4545754,
      "lng":4546486
    }
  }
}

List Results for project :

{
  "results":[
    {
      "image_url":"http://www.sengab.com/projects_uploads/31.jpg",
      "caption":"Accident in Tahrir Square",
      "location": {
        "lat":5568,
        "lng":5775
      }
    }
  ]
}

DESCRIPTION

In this template the contributor is asked to take a photo, briefly describe it and his location will be implicitly sent alongside with them.

The results will be a combination of the contributions, a map with a marker of the user location and his submitted image including the caption.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.image_title	String	Defines the description of required image.

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
image	String	Base64 value of the image.	YES
caption	String	Contributor’s description of his image.	YES
location	Object	Holds the value of the location (longitude/latitude).	YES
location.lat	Number	Holds the value of latitude.	YES
location.lng	Number	Holds the value of longitude.	YES

LIST RESULTS OF PROJECT

results array of objects, each has the following fields.

Parameter	Type	Description
image_url	String	The URL of the photo.
caption	String	Contributor’s description of his image.
contributions_count	Number	count of all contributions for this image
location	Object	Holds the value of the location (longitude/latitude).
location.lat	Number	Holds the value of latitude.
location.lng	Number	Holds the value of longitude.

Template 5

Add project

{  
  "template_id":5,
  "template_body":{  
    "question_title":"Do you see a cat?",
    "images":[  
      {  
        "image":"R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
      },
      {  
        "image":"R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
      }
    ]
  }
}

Get more feed

GET /projects/15214/feed HTTP/1.1
Content-Type: application/json; charset=utf-8

Respone :

HTTP/1.1 206 Partial Content
Content-Type: application/json

{  
  "images":[  
    {  
      "id":6,
      "url":"http://www.sengab.com/projects_images/14/46.jpg"
    },
    {  
      "id":7,
      "url":"http://www.sengab.com/projects_images/14/47.jpg"
    },
    {  
      "id":8,
      "url":"http://www.sengab.com/projects_images/14/48.jpg"
    },
    {  
      "id":9,
      "url":"http://www.sengab.com/projects_images/14/49.jpg"
    },
    {  
      "id":10,
      "url":"http://www.sengab.com/projects_images/14/50.jpg"
    }
  ]
}

Submit contribution

{
  "data": {
    "image_id": 1,
    "answer": "yes"
  }
}

List results of project

{  
  "results":[  
    {  
      "image_id":1,
      "image_url":"http://www.sengab.com/projects_uploads/3/1.jpg",
      "contributions_count":454,
      "yes_percent":54,
      "no_percent":46
    },
    {  
      "image_id":2,
      "image_url":"http://www.sengab.com/projects_uploads/3/2.jpg",
      "contributions_count":77,
      "yes_percent":30,
      "no_percent":70
    }
  ]
}

DESCRIPTION

In this template the project has a large number of photos and we want to know if they are photos of a particular thing or not. e.g you have a 10K photos of some animals and you want to know which photos are photos of cat.

The result of this project will be each photo with the percentage of contributors’ answers to the question.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.question_title	String	The question that will be shown with the photos.
template_body.images	Array[String]	An array of string containing images in Base64.

GET MORE FEED

This request is sent to get 5 more photos that user can contribute identifying them.

GET http://api.sengab.com/v1/projects/<PROJECT_ID>/feed

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
image_id	Number	The image ID of the photo that the user had recognized.	YES
answer	Boolean	User’s answer to the question	YES

LIST RESULTS OF PROJECT

results array of objects, each has the following fields.

Parameter	Type	Description
image_id	Number	The ID of the photo.
image_url	String	URL of the image.
contributions_count	Number	count of all contributions for this image.
yes_percentage	Number	The percentage of the positive answer that the photo had received.
no_percentage	Number	The percentage of the negative answer that the photo had received.

Template 6

Add project

{
  "template_id": 6,
  "template_body": {
    "question_title": "Write what you read",
    "images": [
      {
        "image": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
      },
      {
        "image": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
      }
    ]
  }
}

Get more feed

GET /projects/15214/feed HTTP/1.1
Content-Type: application/json; charset=utf-8

Respone :

HTTP/1.1 206 Partial Content
Content-Type: application/json

{  
  "images":[  
    {  
      "id":6,
      "url":"http://www.sengab.com/projects_uploads/14/46.jpg"
    },
    {  
      "id":7,
      "url":"http://www.sengab.com/projects_images/14/47.jpg"
    },
    {  
      "id":8,
      "url":"http://www.sengab.com/projects_images/14/48.jpg"
    },
    {  
      "id":9,
      "url":"http://www.sengab.com/projects_images/14/49.jpg"
    },
    {  
      "id":10,
      "url":"http://www.sengab.com/projects_images/14/50.jpg"
    }
  ]
}

Submit contribution

{
  "data": [
    {
      "image_id": 1,
      "text": "Sengab is just awesome!!"
    }
  ]
}

List results of project

{  
  "results":[  
    {  
      "image_id":1,
      "image_url":"http://www.sengab.com/projects_imags/3/1.jpg",
      "contributions_count":600,
      "text":[  
        "Sengab is just awesome!!",
        "sengab is just awesome"
      ]
    },
    {  
      "id":2,
      "image_url":"http://www.sengab.com/projects_imags/3/2.jpg",
      "contributions_count":454,
      "text":[  
        "GitHub is how people build software."
      ]
    }
  ]
}

DESCRIPTION

In this template the project has a large number of scanned photos that contain text and we want to extract the text written from them. e.g you have a very old scanned book with hundreds of photos, and you want to convert it to a digital book, you will split it into a large number of photos and upload them to the project, then see the magic.

The result of this project will be every photo beside the all the text provided by the users for it.

ADD PROJECT

Parameter	Type	Description
template_id	Number	Defines the template type.
template_body	Object	Defines the template body.
template_body.images	Array	An array of objects containing images in Base64 and their IDs.
template_body.images.image	String	The image represented in Base64.

GET MORE FEED

This request is sent to get 5 more photos that user can contribute identifying them

GET http://api.sengab.com/v1/projects/<PROJECT_ID>/feed

SUBMIT CONTRIBUTION

data object, holds contribution data (response).

Parameter	Type	Description	Required
image_id	Number	The image ID of the photo that the user had recognized.	YES
text	String	User’s recognition to the text in the photo	YES

LIST RESULTS OF PROJECT

results array of objects, each has the following fields.

Parameter	Type	Description
image_id	Number	The ID of the photo.
image_url	String	URL of the image.
text	Array[String]	A list holds all the text provided from the user for this photo.

Users

Get user profile

GET /users/<ID> HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

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

{
  "id": "user::11",
  "first_name": "Ahmad",
  "last_name": "El-Melegy",
  "gender": "male",
  "image": "https://lh3.googleusercontent.com/.../photo.jpg",
  "about": {
    "email": "ahmad.melegy@gmail.com",
    "bio": "GEEK , CSE student, CAT Reloaded Member"
  },
  "stats": {
    "projects": 0,
    "contributions": 26
  },
  "projects": "http://api.sengab.com/v1/users/user::11/created_projects",
  "contributions": "http://api.sengab.com/v1/users/user::11/contributions",
  "url": "http://api.sengab.com/v1/users/user::11",
  "enrolled_projects": [
    "project::1",
    "project::2",
    "project::3",
    "project::4",
    "project::5"
  ]
}

This endpoint retrieves user’s profile.

HTTP Request

GET http://api.sengab.com/v1/users/<USER_ID>

List User’s Activity

GET /users/<USER_ID>/activities HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": 1,
    "activity_type": "contribution",
    "created_at": "2016-02-12T03:21:55Z",
    "project": {
      "id": "project::1",
      "name": "Project of template 1",
      "url": "http://api.sengab.com/v1/projects/project::1"
    }
  },
  {
    "id": 2,
    "activity_type": "contribution",
    "created_at": "2016-02-12T03:21:55Z",
    "project": {
      "id": "project::2",
      "name": "Project of template 2",
      "url": "http://api.sengab.com/v1/projects/project::2"
    }
  }
]

This endpoint retrieves all user’s activities.

HTTP Request

GET http://api.sengab.com/v1/users/<ID>/activities

List enrolled projects

GET /users/<USER_ID>/enrolled_projects HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "project::5",
    "name": "Say what you see",
    "url": "http://api.sengab.com/v1/projects/project::5",
    "image": "http://www.sengab.com/projects_images/1.jpg",
    "owner": {
      "id": "user::8",
      "name": "Amr El-Masry",
      "url": "http://api.sengab.com/v1/users/user::8",
      "image": "http://Sengab.com/users_images/user_5.png"
    },
    "created_at": "2008-01-14T04:33:35Z",
    "brief_description": "This a brief description about this project",
    "enrollments_count": 700,
    "contributions_count": 510,
    "template_id": 3,
    "category": {
      "id": "category::2",
      "name": "Visual",
      "url": "http://api.sengab.com/v1/categories/category::2"
    }
  }
]

This endpoint retrieves all projects that the user enrolled in.

HTTP Request

GET http://api.sengab.com/v1/users/<USER_ID>/enrolled_projects/

List created projects

GET /users/<user-id>/created_projects HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "project::5",
    "name": "Say what you see",
    "url": "http://api.sengab.com/v1/projects/project::5",
    "image": "http://www.sengab.com/projects_images/1.jpg",
    "owner": {
      "id": "user::8",
      "name": "Amr El-Masry",
      "url": "http://api.sengab.com/v1/users/user::8",
      "image": "http://Sengab.com/users_images/user_5.png"
    },
    "created_at": "2016-02-12T03:21:55Z",
    "brief_description": "This a brief description about this project",
    "enrollments_count": 700,
    "contributions_count": 510,
    "template_id": 3,
    "category": {
      "id": "category::2",
      "name": "Visual",
      "url": "http://api.sengab.com/v1/categories/category::2"
    }
  }
]

This endpoint retrieves all projects created by the user.

HTTP Request

GET http://api.sengab.com/v1/users/<USER_ID>/created_projects/

Enrollment

Enroll in a project

POST /me/enrollments/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: X-Auth-Token YOUR_ACCESS_TOKEN

The above command returns JSON structured like this

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

{
  "project_id": "project::3",
  "url": "http://api.sengab.com/v1/projects/project::3"
}

This endpoint enrolls a user in a project.

HTTP Request

POST http://api.sengab.com/v1/me/enrollments

Parameter	Required
project_id	YES

Withdraw from project

DELETE /me/enrollments HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: X-Auth-Token YOUR_ACCESS_TOKEN

The above command returns JSON structured like this

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

{
  "project_id": "project::3",
  "url": "http://api.sengab.com/v1/projects/project::3"
}

This endpoint withdraws a user from a project.

HTTP Request

DELETE http://api.sengab.com/v1/me/enrollments

Parameter	Required
project_id	YES

Categories

List all categories

GET /categtories HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "category::6",
    "url": "http://api.sengab.com/v1/categories/category::6",
    "name": "charity",
    "image": "http://www.sengab.com/categories_images/431.jpg",
    "description": "This category contains all projects related to charity"
  },
  {
    "id": "category::5",
    "url": "http://api.sengab.com/v1/categories/category::5",
    "name": "health",
    "image": "http://www.sengab.com/categories_images/458.jpg",
    "description": "This category contains all projects related to heath"
  },
  {
    "id": "category::1",
    "url": "http://api.sengab.com/v1/categories/category::1",
    "name": "health",
    "image": "http://www.sengab.com/categories_images/458.jpg",
    "description": "This category contains all projects related to heath"
  },
  {
    "id": "category::4",
    "url": "http://api.sengab.com/v1/categories/category::4",
    "name": "sports",
    "image": "http://www.sengab.com/categories_images/495.jpg",
    "description": "This category contains all projects related to sports"
  },
  {
    "id": "category::3",
    "url": "http://api.sengab.com/v1/categories/category::3",
    "name": "sports",
    "image": "http://www.sengab.com/categories_images/495.jpg",
    "description": "This category contains all projects related to sports"
  },
  {
    "id": "category::2",
    "url": "http://api.sengab.com/v1/categories/category::2",
    "name": "sports",
    "image": "http://www.sengab.com/categories_images/495.jpg",
    "description": "This category contains all projects related to sports"
  }
]

This endpoint retrieves all categories.

HTTP Request

GET http://api.sengab.com/v1/categories

List projects of a category

GET /categtories/458 HTTP/1.1
Content-Type: application/json; charset=utf-8

The above command returns JSON structured like this

HTTP/1.1 206 Partial Content
Content-Type: application/json

[
  {
    "id": "project::4",
    "name": "project 4",
    "owner": {
      "id": "user::6",
      "url": "http://api.sengab.com/v1/users/user::6",
      "name": "Ahmed Rashwan",
      "image": "http://Sengab.com/users_images/user_6.png"
    },
    "url": "http://api.sengab.com/v1/projects/project::4",
    "goal": 159,
    "image": "http://Sengab.com/projects/prject::4/image.png",
    "template_id": 1,
    "created_at": "2015-02-15T04:33:35Z",
    "brief_description": "short",
    "enrollments_count": 489,
    "contributions_count": 123,
    "category": {
      "category_id": "category::6",
      "url": "http://api.sengab.com/v1/categories/category::6",
      "name": "charity"
    }
  }
]

This endpoint retrieves projects of a category.

HTTP Request

GET http://api.sengab.com/v1/categories/<CATEGORY_ID>

Contributions

Submit a contribution in a project

POST /me/submissions HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: X-Auth-Token YOUR_ACCESS_TOKEN

The above command returns JSON structured like this

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "contribution::1::5",
    "url": "http://api.sengab.com/v1/contributions/contribution::1::5"
}

The above response is for a contribution to project with id equals project::1 submitted by user with id equals user::5

This endpoint submits a contribution to a project.

HTTP Request

POST http://api.sengab.com/v1/me/submissions

Request body:

Parameter	Description	Required
user_gender	Contributor’s gender.	YES
project_id	Project ID.	YES
contribution	Contribution object, see below.	YES
contribution.created_at	Date of contribution.	YES
contribution.data	Content of data will be different according to the project template, for more check Templates section.	YES

Pagination

Most methods in the API accept the offset and limit parameters for fetching specific pages of results from the API. Offset refers to starts at and defaults to 1, limit can be any value between 0 and 100 and defaults to 10.

Parameters

Name	Type	Required	Description
offset	Number	No	The offset of the first record returned. Default is 0.
limit	Number	No	The number of records returned. Default is 10

Errors

Our API responses indicating an error or warning are represented by a proper response HTTP status code (403, 404, etc) alongside with a response body containing the following information:

Attribute	Type	Description
status	Number	The corresponding HTTP status code.
code	Number	A specific error code that can be used to obtain more information.
message	String	A simple, easy to understand message that you can show directly to your application’s end-user.

Our API uses the following error codes:

Error Code	Meaning	Details
400	Bad Request	Your request sucks !
401	Unauthorized	Authentication credentials are required to access the resource. All requests must be authenticated.
403	Forbidden	The supplied authentication credentials are not sufficient to access the resource.
404	Not Found	We could not locate the resource based on the specified URL.
405	Method Not Allowed	This request is not supported for the resource.
406	Not Acceptable	You requested a format that isn’t JSON.
409	Conflict	The request could not be completed due to a conflict with the current state of the target resource.
500	Internal Server Error	We had a problem with our server. Try again later.
503	Service Unavailable	We’re temporarily offline for maintenance, Please try again later.

DB Entities

User

Parameter	Type	Description	Example
ID	String	Format : user::Google user Id	user::12348756
type	String	The type of the document	user
url	String	URL for user object
first_name	String
last_name	String
image	String	Url for user avatar
about	object	Holds location which is the user country, email and bio short description of the user.
stats	object	Count of created projects and contributions of user.
projects	String	URL for created projects by the user.	http://api.sengab.com/v1/users/1411414/created_projects
contributions	String	URL for the user contributions.	http://api.sengab.com/v1/users/1411414/contributions
created_at	String	Profile created date.	ISO 8601 format.
activity	String	URL for User Activity	http://api.sengab.com/v1/users/1411414/activities

Activity

Parameter	Type	Description	Example
ID	String	Format : activity::userID	activity::1411414
type	String	The type of the document	activity
activity	object	Entry for user’s activity. contains activity_id, activity_type, project which is the project related to this activity and created_at.
activity.project	object	Entry for the project related to this activity. Contains project_id,project_url,project_name

Category

Parameter	Type	Description	Example
ID	String	Format: category::UUID	category::4573
url	String	URL for category
name	String	Category name
image	String	URL for category image
description	String	Description of the category

Project

Parameter	Type	Description	Example
ID	String	Format : project::UUID
url	String	URL for the project
name	String	Name of the project
image	String	URL for the project image
owner	object	Project creator. contains the user_id, url and name	"owner" : { "id":11, "url":"http://api.sengab.com/v1/users/11" , "name":"Galileo Galileo" }
created_at	String	Project created date	ISO 8601 format
enrollments _count	int	Count of enrolled users to this project.
contributions _count	int	Count of contributions to this project.
brief_description	String	Short project description.
detailed_description	String	Detailed project description.
category	String	Document id for the category this project belongs to.	category::15894238
results	String	Document id for the results of this project. Format: result::project_id	result::548621
stats	String	Document id for the stats of this project. Format: stats::project_id	stats::548621
template	object	The project’s template. Contains the template_id (String) and the template_body(object).	{ "template_id":1,"template_body":{"question_title":"_are you happy today?" } }

Stats

Parameter	Type	Description	Example
enrollments_count	int	Count of enrolled users to this project.
contributions_count	int	Count of contributions to this project.
contributors_gender	object	Count of the gender of contributors. Contains: male(int), female(int) or unknown.	“contributors_gender”:{“male”:8, ”female”:7, “unknown”: 3 }
contributors_location	object	Count of the countries of the contributors. Contains: country_name(int)	“contributors_location”:{“Egypt”:8,”USA”:7}

Result

Parameter	Type	Description	Example
ID	String	Format: result::project_id
result	object	Contains anonymous contribution info that differs from one template to the other	{“result”:{"image_url":"http://www.sengab.com/projects_uploads/56842.jpg", "caption":"My cat lily"}

Contributions

Parameter	Type	Description	Example
ID	String	Format: contributions::project_id::user_id
url	String	URL of the contribution
project	String	Document ID for the related project.	project::159845
contributor	String	Document ID for the contributor.	user::715628
created_at	String	Generated by the client
data	object	Content of contribution data will be different according to the project template.	"data":{ "first_name": "Emma", "last_name": "Watson" }