SocialChorus API Guidance
This document provides information about concepts and behaviors that apply broadly across the API.
Security and Scalability
The SocialChorus system is designed to be horizontally scalable allowing large numbers of concurrent users to use the platform with no impact on availability, consistency, or performance. The platform follows scalability best practices, ensuring that performance and availability adhere to system SLAs regardless of user load.
All customer data must be encrypted in transmission from and to customer facing applications using industry standard AES-256 bit encryption.
Our security practices include:
- End-to-end Data Encryption: Using the proven AES-256 standard, we encrypt every bit of data in transit and at rest.
- Security Certifications & Compliance: SOC 1, Type I & SOC 2, Type II; CIS AWS Foundations Benchmark v1.0.0 compliant; AWS is ISO 27001 & SOC 1, 2, & 3.
- Continuous Auditing: We regularly review and audit our security protocols to ensure data protection and monitoring 24/7/365.
A detailed overview of the SocialChorus security and operational policies is available in our Operational Excellence document (contact SocialChorus at email@example.com for a copy).
Response properties of similar types use conventions in both their key and value formatting.
- Timestamp property names use the _at suffix, such as ‘created_at’. Timestamp property values use ISO 8601 format in UTC timezone.
- Datestamp properties use the _on suffix, such as ‘joined_on ’. Datestamp property values use ISO 8601 format and rendering of the value uses UTC timezone if the source value includes time information.
- URLproperties are simple text type data but use the _urlsuffix, such as ‘ image_url’. They always provide full URLs, including host.
- Derived Data, or properties that offer an alternative formatting of another property, indicate in their property name the added formatting. For example, a content response property called “body” may be accompanied by a second property that wraps the body in HTML. The two properties are then called ‘body’ and ‘body_html’.
Endpoints are accessed at https://partner.socialchorus.com/v2/.
All requests must use the HTTPS protocol. This ensures that all information transferred between client and server is encrypted and protected.
All requests must provide an Authorization header as defined by the Authentication and Authorization section of these docs. The bearer token format used by the OAuth standard is:
Authorization: Bearer <access token>
Where “<access token>” is replaced with an access token for the acting user.
curl -H "Authorization:Bearer <your_OAuth_token>" 'https://partner.socialchorus.com/v2/content'
If OAuth requirements are not met, 401 (user not found or not identified based on access token in request) and 403 (user permission) responses are returned. (Refer to the “Client Errors” section for more details.)
Verbs and Routes
Endpoints in the SocialChorus Partner API use RESTful URLs and request methods in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the route and methods expected, but the following describes the typical operations you can expect to encounter:
- Reading of data in either list or individual form; use GET
- Creating of new records; use POST
- Updating of existing records; use PUT
- Executing actions on existing records (such as “archive” or “publish”); use PUT
- Deletion of records or data; use DELETE
PUT operations are generally idempotent actions, meaning that making the request twice will have no different effect than calling it once. Calling a POST request twice, on the other hand, can be expected to create two records.
Endpoints will often identify the record being operated against in the URL itself. For example, a URL that describes a content post will use the RESTful URL format GET /v2/channels/123 where “123” is the ID of the channel record.
Furthermore, entities or resources nested within a parent resource will also typically be identified in the URL. A list of content within a channel would be represented as GET /v2/channels/123/content; and a specific content record within a channel, as GET /v2/channels/123/content/456. These are broad patterns used in the API and each endpoint will specify the URL to use.
Some endpoints provide the ability to sort the returned records. Usually these are endpoints that list records, such as an endpoint for listing all channels or for listing the users in the program.
Endpoints allowing sorting will always use the same ?sort=<parameter> query to declare the intended sort order. The parameters by which an endpoint can be sorted will be listed in that endpoint’s documentation.
Sorting is in ascending order by default, but can be inverted to descending order using a “-” character in front of the parameter name. For example, ?sort=-title sorts the records by title in descending order, with a record titled “Zoo” listed before a record titled “Animal”.
Multiple sort parameters can also be provided using a comma as delimiter between parameter names. The query ?sort=title,created_at will sort the records by title, and for any records with the same title, the created_at property will then determine the order in which they’re returned.
Attempting to sort by a parameter not supported by a given endpoint can be expected to return a 400 Bad Request response.
Some endpoints allow filtering of returned items; these are endpoints that return top-level collections of data and statistics-related requests. Requested filters must be formatted as a dictionary within the `filter` parameter.
By default, filters are enum-based (for example, “published|archived|draft”), where items that match the filter are exact matches to the provided filter value. When possible, endpoints allow for filtering items by any property provided in the resource. Exceptions apply for cases such as long text properties.
Resources with timestamp properties offer range-based filters including `.from` and `.to`. Timestamp filters accept either timestamps (2018-05-01T17:36:52) or datestamps (2018-05-01) in ISO 8601 format. Datestamp values are assumed to be in UTC.
Example filters where `created_at` is a resource property:
When multiple filters are used in a single request, the filters are combined using intersection. Specifying the filters foo=1&bar=2 yields items that have a foo value of ‘1’ and a bar value of ‘2’ (“this AND that”; not “this OR that”).
When a filter allows for multiple values to be matched, values can be provided as a list, using either a comma-delimited string or an array of strings. Filters that allow for multiple values by default operate in a “match ANY” behavior. Specify the filter foo=bar,baz will yield items that either have a foo value of “bar” or “baz”. Endpoint filters that use a different behavior will specify their behavior in the documentation.
Filter values provided in a request that cannot be parsed or do not match expected formats result in a 400 Bad Request response.
Many endpoints that return top-level collections of data allow for pagination of returned items. The requested page specification must be formatted as a dictionary within the `page` parameter.
Page number can be provided as `page[number]` and defaults to 1. Page size can be provided as `page[size]`. Each endpoint specifies its own default page size.
For endpoints that provide feed-based pagination, page cursors can be provided as `page[cursor]` where the value is the resource id of the last item in the previous request.
Pagination values provided in a request that cannot be coerced or that exceed specified ranges result in a 400 Bad Request response.
Pagination values that request ranges not available (for example, requesting page 4 when there is only enough data for 3 pages) will respond with an empty data set and pagination metadata showing that the requested page is out of range.
Responses in the SocialChorus Partner API use RESTful response bodies in order to be descriptive and predictable. Each endpoint includes its own documentation illustrating the responses and errors expected, but this section describes the typical responses you can expect to encounter.
Every response provides the following special response headers:
- X-Program-Id: the program id of the scope of the request
- X-User-Id: the user id of the acting (authenticated) user
Endpoints that return data will always wrap that data in a “data” property, whether the response data is a dictionary or array.
Successful responses that return data always wrap their data in a “data” property and include a “meta” object at the root level when meta information is available (Refer to the Metadata section for details).
While different endpoints use different response codes that correspond to the purpose and design of the endpoint, the following are general patterns you can expect:
- Reading of data in either list or individual form uses 200 Ok.
- Creating new records uses 201 Created if a record was created immediately, and 202 Accepted if a record will be created but cannot be completed immediately.
- Updating existing records uses 200 OK if the record was updated immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
- Executing actions on existing records (such as “archive” or “publish”) uses 200 OK if the record was updated immediately and 202 Accepted if the update will be performed but cannot be completed immediately. In some cases, if the action does not need to respond with any data, 204 No Content indicates immediate success without a response body.
- Deletion of records or data uses 200 Ok if the data was deleted immediately, and 202 Accepted if the update will be performed but cannot be completed immediately.
Each endpoint will describe the response statuses it returns.
Every successful response provides metadata relating to the response in the root of the response body. The meta property includes information that helps to explain the aspects that went into determining what data to return in the response, including pagination, filtering, and sorting.
For endpoints that allow pagination, the metadata includes a `page` property. The page property includes values used in pagination even if the request did not specify a page.
- size: The coerced or defaulted page size value from the request
- number: The coerced or defaulted page number value from the request
- total_records: A count of the total items in the collection according to the filters.
For endpoints that allow filtering, the metadata includes a `filters` property. The filters property includes default values used in filtering even if the request did not specify filters. For example, if a filter such as “status” is set to “registered” by default, the filter’s property will include `status: “registered”`.
For endpoints that allow searches, the metadata includes a `search` property that indicates the value of the search param used in the request. If the search property was reformatted or transformed in any way, it will be represented in the meta properties in its transformed format.
For endpoints that allow sorting, the metadata includes a `sort` property that indicates the list of sort keys used in order.
All errors (4xx and 5xx) response bodies will be wrapped in an “error” structure containing the following fields:
- code (the numeric error code)
- title (the name of the error)
- detail (a description providing additional information)
"title": "Unauthorized Access”,
"detail": "<Message about authorization>"
Some errors include additional data fields containing information about the error. For example, a validation error will contain a `validations` field as shown below:
"title": "Bad Request",
"detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.",
"detail": "Title is required",
Client Error Codes
Error codes in the range 400 - 499 indicate invalid input or improper use of the API. Clients should alter their request to correct the indicated error before trying the request again.
Bad Request: A request parameter or formatting does not match an expected required format. Typical cases include:
- Missing a required parameter
- Invalid formatting of a parameter, such as providing a timestamp filter where the parameter value cannot be coerced to a date or time
- Page number or size is not in valid range
Validation errors include an additional `validations` parameter that contains an array of validation entries specific to individual parameters in the request. Each entry has the following format:
Unauthenticated: Returned when a required access token is not provided. See “Authentication and Authorization” for details.
Forbidden: The Authenticated User does not have permissions required to perform the action requested.
Not Found: Returned when a primary resource is not found. A primary resource can be defined as resource scoped in the URL of the endpoint. For example, the URL `channels/123/content/456` results in 404 if the channel or the content doesn't exist, or if the content exists but is not associated to the channel. Additionally, requests for contextually private resources may return 404 as a way to avoid revealing the presence of the resource.
Server Error Codes
Error codes in the range 500 - 599 indicate an error on the server. Clients should retry their request again later, or contact support for assistance.
Internal server error
- End-to-end Data Encryption: Using the proven AES-256 standard, we encrypt every bit of data in transit and at rest.