api.seacontact.com

API

Quick notes and usage reference for
seacontact.com API.

Methods

Here you can find current methods supported by the api

Standart Fields

In this section you can find list of standart fields, information in this section is dynamicaly taken from the engine so you can refer to it when querying the api.

For each parameter you can specify coma separated name of fields returned by the request. Acceptable parameters and fields are:

For comments, likes, notifications, and some other objects you will need to specify 'section' and 'section_id' parameters. Allowed sections you can find here:

Authorization

Any requests to the API could be done only with token, which can be obtained after successfull authorization by Oauth 2.0 workflow

If you perform a GET request to users.get method wihtout authorization:

GET /users.get HTTP/1.1
Accept: Application/json

This will return an error:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="Service"
Connection: close
Content-Type: application/problem+json
{
	"type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
	"title":"Forbidden",
	"status":403,
	"detail":"Forbidden"
}

OAuth2

OAuth2 is an authentication framework used worldwide; for instance Facebook , Github, and Twitter use this protocol to authenticate their APIs. Before introducing the Apigility OAuth2 functionalities, let's briefly look at the core concepts of this authentication system.

The use cases covered by the OAuth2 framework are:

• Web-server applications
• Browser-based applications
• Mobile apps
• Username and password access (Confidential/Public)
• Application access

Currently Seacontact API supports only (Confidential Clients) Username and password access
You need application client_id and client_secret to get access to the API, and user email and password to perform requests on behalf of user.

The authentication mechanism is just 1 step:

The client application provides the client_id and client_secret as HTTP Basic authentication credentials, and the username, and password values in the request body, in order to obtain an access token

POST testclient:testpass api.seacontact.com/oauth HTTP/1.1
Accept: application/json
Authorization: Basic dGVzdGNsaWVudDp0ZXN0cGFzcw==
Content-Type: application/json
{
	"grant_type": "password",
	"username": "vasya@mail.ru",
	"password": "testpass"
}

If authorization is successfull you will receive access token:

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

{
	"access_token":"e8a9f857f0f02bc5d0b066b94d341bedd9dc2646",
	"expires_in":9999999,
	"token_type":"Bearer",
	"scope":null,
	"refresh_token":"bc83f6830eda81bf79392592a1a0fd6f20fe7dbb"
}

Refresh OAuth2 token

The OAuth2 protocol gives you the possibility to refresh the access token, generating a new one with a new lifetime. This action can be performed using the refresh_token that the OAuth2 server provides in the response during the authentication step. In Apigility, you can refresh the access token with a POST to the OAuth2 server endpoint. Check the following example of refreshing token:

POST api.seacontact.com/oauth HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "[the refresh_token]",
"client_id": "testclient",
"client_secret": "testpass"
}

The response will be something like:

HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "470d9f3c6b0371ff2a88d0c554cbee9cad495e8d",
"expires_in": 3600,
"scope": null,
"token_type": "Bearer"
}

Obtained token can be used for making requests to the API

Requests to the API

HTTP Methods Negotiation

Api takes care of HTTP method negotiation for you. This means if a request is made via a method you have not allowed, it will report this to the user with a 405 status code, and also report which methods are allowed via the Allow response header.

HTTP/1.1 405 Method Not Allowed
Allow: GET

Content Negotiation

Currently API support requests and response in JSON. If you specify a different media type in the Accept header, it reports that it cannot handle it.

If you perform a GET request to the service, and specify that you want HTML:

GET api.seacontact.com/users.get HTTP/1.1
Accept: text/html

This will return an error:

HTTP/1.1 406 Not Acceptable
Content-Type: application/problem+json
{
"detail": "Cannot honor Accept type specified",
"status": 406,
"title": "Not Acceptable",
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

try requesting JSON:

GET api.seacontact.com/users.get HTTP/1.1
Accept: application/json

This will work!

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"data_list":[{
	"user_id":"39077",
	"name":"vasya batareykin",
	"surname":"*******",
	"full_name":"*******",
	"email":"*******",
	"contact_mobile":"*******",
	"desired_rank":"*******"
	}],
"total_results":"38677",
"_page":1,
"_limit":"1"
}

Terminology

Entity

An object of information: user, vacancy or question item. Each item can contain fields

Field

A property of an Entity, it can be username or likes quantity for the blog post

Collection

A addressable set of entities. Typically, all entities contained in the collection are of the same type

Most of the GET methods of the API returning a collection of entities.

Request

Every request to the collection can contain standart fields:

_%name of section%_fields

Comma separated list of entity fields

_limit

Quantity of results per page, required for pagination, maximum is 100

_page

Current page of collection

Filters

Other parameters to filter the result

Response

Every Collection response have a standart fields:

data_list

List of entities

total_results

Total quantity of entities for that query

_limit

Quantity of results per page

_page

Current page

When requesting a collection you can specify which fields should be returned in response.
Usualy every entity has its own fields, lets say, for the question entity it will be id, title, text etc.
to specify question fields add comma separated names of them with the _question_fields option in request.

GET /questions.get?_question_fields=id,title,text&access_token=e8a9f857f0f02bc5d0b066b94d341bedd9dc2646

Some collection also have additional fields associated with item, lets say every question also have a user which had posted it.
For this collections you can specify _user_fields parameter, with comma separated field names

GET /questions.get?_question_fields=id,title,text&_user_fields=user_id,login,name,surname&access_token=e8a9f857f0f02bc5d0b066b94d341bedd9dc2646

For filtering the result you can specify required values for other fields in the request. You can refer this example to see some of the options

GET /questions.get?_question_fields=id,title&_user_fields=id,login,name,surname&_stats_fields=answers,likes&unanswered=1&query=море&_limit=2&access_token=38f6aba03e7f969d83fd2ddebd6038039a79cda3

And typical response will be

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
	"data_list":[
		{
			"question_id":"20",
			"id":"38901",
			"title":"\u041c\u0435\u0434\u0438\u0446\u0438\u043d\u0441\u043a\u0438\u0435 \u0441\u0435\u0440\u0442\u0438\u0444\u0438\u043a\u0430\u0442\u044b",
			"user_id":"38901",
			"login":"IgorrSidorenko",
			"name":"Igor",
			"surname":"*******",
			"likes":"0",
			"answers":"3"
		},
		{
			"question_id":"17",
			"id":"38901",
			"title":"\u0420\u0430\u0437\u043d\u0438\u0446\u0430 \u0434\u0438\u043f\u043b\u043e\u043c\u043e\u0432",
			"user_id":"38901",
			"login":"IgorrSidorenko",
			"name":"Igor",
			"surname":"*******",
			"likes":"0",
			"answers":"0"
		}
	],
	"total_results":"7",
	"_page":1,
	"_limit":"2"
}

For more detailed information please refer to the Standart Fields section and Methods section