Damir Simunic edited this page Apr 16, 2015 · 3 revisions

The Communities.CC is fully API enabled. All data manipulation on the site happens through the API.

API endpoint

The API HTTP endpoint for all requests is http://communities.cc/__api/v1/*operation-name*

Mandatory Parameters

All requests must include the following query parameters (whether POST or GET):

key				        # api key
request-time			# request time
signature				# SHA1 signature

The request_time must be UTC, using format YYYY-MM-DDTHH:MM:SS

The operation must be specified as part of the HTTP endpoint.

Signing Requests

To sign a request, concatenate values of the first three parameters with API password and hash with SHA1. Concatenation of values should be without any delimiters, and should be in this order:

operation api_key password request_time

Supplied time in request_time parameter must be within 2 minutes of the server time, otherwise the request will fail.

The robust way to send requests is to request the server time before signing and issuing each API operation.

Allowed HTTP Status Codes

The receiving system authenticates the request, executes the operation and responds with the following HTTP status codes:

  • 200 OK for successfully authenticated and executed operations,
  • 403 Forbidden for requests it cannot authenticate,
  • 404 Not found if the operation cannot find the requested object,
  • 500 Error if the operation is authenticated but cannot execute for any other reason.

It is up to the initiating system to implement the logging, retry, and error handling logic.

Operations

time

Returns current server time in UTC. No signature required

The returned string is in the same format as the server-time parameter required for all signed operations.

echo

Dumps all headers from the request. No signature required.

This is a convenience operation used during development and debugging.

The response always contains the header X-C3-AuthSucceeded which can take values yes or no. It returns yes if the request is properly signed and successfully authenticated. If not signature is included, or if the server could not authenticate the signature, the value is no.

Parameters

fields		# a comma separated list of headers to return
postonly	# return only the contents of Request.Forms

communities

Return a list of communities in the catalog. The return value is a json string containing an array with community data. Note that automatically calculated tags (such as Size tag group) are not returned.

[
  {
    "dn": "OLDER PERSONS INTERESTS",
    "Uri": "http://community.eldis.org/oldagegroup",
    "Age": 632,
    "Members": 81,
    "Contributions": 0,
    "Contributors": 0,
    "Countries": 0,
    "last": 632,
    "tags": [
      "Theme:Ageing",
      "Host:Eldis-communities"
    ]
  },
  {
    "dn": "1st African World Cup",
    "Uri": "http://community.eldis.org/worldcup",
    "Age": 1755,
    "Members": 41,
    "Contributions": 0,
    "Contributors": 0,
    "Countries": 0,
    "last": 1755,
    "tags": [
      "Theme:General development",
      "Host:Eldis-communities"
    ]
  },

Parameters

limit           # Maximum count of communities to return
tags            # A list of tags in the format `tag-group:tag-name,...`

If no tags are specified, an unfiltered list is provided, up to the specified limit.

add-community

Add new community to the catalog.

Parameters

name			# Community name
description		# community description
displayname		# The human-friendly community name
url             # Url of the community homepage
join_url        # Url of the community's join page
image_url       # Url of the image representing the community (usually called 'hero image') or a community logo
created_on      # Date the community was created;  must be UTC, using format `YYYY-MM-DDTHH:MM:SS`
last_active     # Date of the most recent contribution;  must be UTC, using format `YYYY-MM-DDTHH:MM:SS`
members         # Number of community members
contributions   # Total number of contributions 
contributors    # Number of contributors
countries       # Number of countries members are from
id              # A string representing the unique identifier of the community in the source database
hash            # A hash of community's values. This value is opaque for the api, and is returned to the caller in the `state` operation to help the synchronization process
tags            # A comma-separated list of tags
source          # The name of the source host; can be URL or a string

Only the displayname, url, source, and id are mandatory.

update-community

Update an existing community in the catalog.

Parameters

name			# Community name
description		# community description
displayname		# The human-friendly community name
url             # Url of the community homepage
join_url        # Url of the community's join page
image_url       # Url of the image representing the community (usually called 'hero image') or a community logo
created_on      # Date the community was created;  must be UTC, using format `YYYY-MM-DDTHH:MM:SS`
last_active     # Date of the most recent contribution;  must be UTC, using format `YYYY-MM-DDTHH:MM:SS`
members         # Number of community members
contributions   # Total number of contributions 
contributors    # Number of contributors
countries       # Number of countries members are from
id              # A string representing the unique identifier of the community in the source database
hash            # A hash of community's values. This value is opaque for the api, and is returned to the caller in the `state` operation to help the synchronization process
tags            # A comma-separated list of tags
source          # The name of the source host; can be URL or a string

The displayname, url, source, and id are mandatory. The community with the specified source and id values must exist, otherwise the api will return a 404 error.

delete-community

Delete a community from the catalog.

Parameters

id              # A string representing the unique identifier of the community in the source database
source          # The name of the source host; can be URL or a string

The source and id are mandatory. The community with the specified source and id values must exist, otherwise the api will return a 404 error.

state

Returns a list of community ids and hashes as written by the client. The format is a text file with pair id hash on each line, separated by a single space. The purpose of the state list is to help the synchronization process for hosts that do not provide reliable means of detecting the community changes on each call.

When using the state operation, the caller is supposed to download a list of communities and calculate the hash for each community in any way that will allow detecting changes (for example, converting each community to json and then hashing the resulting string). Next, the caller should download the state from Communities.cc, compare the newly calculated hashes against it, and proceed to upload only communities whose hashes changed, or whose ids do not exist in the state file.

Parameters

source          # The name of the source host used to submit communities previously: can be URL or a string

tags

Returns a list of tags used for display.

Returns a json object containing an array of tag groups:

[{
    "group": "Geography",
    "tags": [
      {
        "id": "Geography:Africa",
        "title": "Africa"
      },
      {
        "id": "Geography:Americas",
        "title": "Americas"
      },
      {
        "id": "Geography:Asia",
        "title": "Asia"
      },
      {
        "id": "Geography:Europe",
        "title": "Europe"
      },
    ...
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.