Introduction

This is the place to start learning about the Crowdynews Web APIs. If you have any questions that you feel are unanswered here, hit us up on Twitter, or send an email to [email protected].

About the Web APIs

Your applications can interact with the Crowdynews platform through the Crowdynews Web APIs. Unless specified otherwise, you can access these APIs at https://api.crowdynews.com.

Authentication and Authorization

Unless specified otherwise, you'll require a valid OAuth access token with correct permissions to access all endpoints. Authentication and Authorization happens through the Crowdynews Authorization API at https://auth.crowdynews.com.

For more information about authentication and authorization, see the Authorization Guide.

Requests

The Crowdynews Web APIs are based on REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use appropriate HTTP verbs for each action:

VERB DESCRIPTION
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for replacing resources.
PATCH Used for partially updating resources.
DELETE Used for deleting resources.

We try to comply to REST principles as much as possible.

Responses

All data is received as a JSON Object.

Resources

Every JSON resource Object contains at least the following fields:

KEY VALUE TYPE VALUE DESCRIPTION
_id String A unique 24 character hexadecimal resource ID.
created String The timestamp that indicates when the resource was created.
createdBy String The consumer who created this resource.
lastModified String The timestamp that indicates when the resource was last modified.
lastModifiedBy String The consumer who last updated this resource.

Resource IDs

These are unique, auto generated, 24 character, hexadecimal Strings.

Timestamps

Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with zero offset: YYYY-MM-DDTHH:MM:SSZ.

Response Status Codes

The API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

STATUS CODE DESCRIPTION
200 OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.
201 Created - The request has been fulfilled and resulted in a new resource being created.
204 No Content - The request has succeeded but returns no message body.
304 Not Modified. Appropriate cache-control headers are required to assist with client-side caching.
400 Bad Request - The request could not be understood by the server due to malformed syntax.
401 Unauthorized - The request requires authentication or, if the request included authentication credentials, authentication has been refused for those credentials.
403 Forbidden - The server understood the request, but is refusing to fulfill it.
404 Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
500 Internal Server Error - An unexpected condition was encountered and no more specific message is suitable.
502 Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.

All 4XX and 5XX reponse bodies contain more information about the occurred error; see Error Details.

Error Details

Unsuccessful responses return information about the error as an error JSON Object containing the following information:

PROPERTY NAME VALUE TYPE DESCRIPTION
requestId String Universally unique identifier for the request in question.
errors Array Contains one or more error objects.

Error Object

An error object contains the following information:

PROPERTY NAME VALUE TYPE DESCRIPTION
name String An error type descriptor.
message String A short description of the cause of the error.
propertyName String Optional. The name of the property the error applies to, if applicable.
propertyValue String Optional. The value of the property the error applies to, if applicable.
reason String Optional. Provides additional information about the error, if any.
code Number Optional. An application specific error code.

Here's the error response you might see when an invalid email address is provided, when trying to create a resource:

HTTP/1.1 400 Bad Request

{
    "requestId" : "b6e884e0-d4bc-11e5-a5c8-bf6ece15db6f",
    "errors": [
        {
            "name": "ValidationError",
            "message": "The provided email address is invalid.",
            "propertyName": "email",
            "propertyValue": "1234",
            "reason": "regexp"
        }
    ]
}