In This Article:

    General Information

    In This Article:

      Call Request/Responses

      The Salsa Engage Developer API is a RESTful API that accepts and produces JSON payloads.

      You need to ensure that the libraries you are using to make calls to the server set the request/response mime-type to application/json, if that is not done, then the proper conversion of the payloads may not occur and will be rejected by our server or your client.

      HTTP Error Codes Returned

      All system-level errors will be reported as standard(or soon to be standard HTTP errors, following is the list of the errors you may encounter:

      Error Code

      Description

      Detail

      400

      Bad Request - Directives in your payload were invalid

      This error would typically occur if the parameters for a search operation are not configured correctly. Such an example is an activity search request without the modifiedFrom attribute set within the payload. In addition to the 400 code, the system will include a description of what the problem was. For example

      200 Bad Request - Either 'modifiedFrom' or 'activityIds' must be provided

      401

      Unauthorized

      Returned when a request without a valid token is made

      429

      Too Many Requests

      A 429 error code will be returned in one of two cases. Either the call rate for the token has been exceeded, or the batch size requested for an operation is larger than what is configured for your token.

      In either case, the 429 will be returned with either one of the following messages

      429 Call rate has been exceeded

      429 Requested batch size exceeds the allowed size of: <token batch size value>

      500

      Internal Server Error

      Non-recoverable error has occurred.

      This exception will also include a JSON structure in the body with additional contextual information which could be provided to Salsa for troubleshooting.

      You should be aware that some of these errors reported in this manner can be resolved on your end.

      An example of such an error is providing an incorrect date format for a search condition. 

       

      Errors Returned Within Payload

      HTTP Code
      Error Code
      Description
      Detail
      200 2012, 2010 Json is not correctly formatted or fields have wrong data format values

      Example:

      {"id":"71defb73-9ee2-4588-a073-a4c6144ce0e1","timestamp":"2018-03-15T21:27:42.946Z","header":{"processingTime":1,"serverId":"srv2"},"errors":[{"id":"6ed546cb-3ab7-482e-be59-42f80aecea94","code":2012,"message":"Unexpected character ('}' (code 125)): expected a value","details":"Reference Chain: payload"}]}

      200 1000 Json document structure is invalid {"id":"d8957a1a-0063-42dc-abe7-49cc3be67b34","timestamp":"2018-03-15T21:30:37.807Z","header":{"processingTime":7,"serverId":"srv2"},"errors":[{"id":"245a9155-ded3-4415-a09f-c2e73e88948c","code":1000,"message":"ignite.core.util.rs.GenericError","details":"Unexpected end-of-input: expected close marker for OBJECT (from [Source: java.io.ByteArrayInputStream@42fd91cb; line: 1, column: 0])\n at [Source: java.io.ByteArrayInputStream@42fd91cb; line: 4, column: 22]"}]}

       

      Understanding Available Calls Remaining

      The API provides an endpoint that enables you to programmatically understand how many calls
      are available before making a request. The returned payload will include the count of available calls as well as operations that have been performed to date for the token.

      GET /api/developer/ext/v1/callMetrics

      • Your authentication token must be set in the HTTP header as parameter   authToken=<your_auth_token> 

      Field

      Description

      rateLimit

      The rate limit configured for your token

      totalAPICalls

      Number of API calls

      currentRateLimit

      Current point in time rate limit - how many calls that can be made before a 429 error will occur

      lastAPICall

      ISO_8601 formatted String with a GMT timezone

      totalAPICallFailures

      Number of API calls that failed

      lastAPICallFailure

      ISO_8601 formatted String with a GMT timezone

      activityFormTypeList

      Activity form type list count

      activityFormList

      Activity form list count

      blastList

      Email blast list count

      activityMetadata

      Activity form metadata count

      activitySummary

      Activity form summary count

      targetedActionTargets

      Targeted action targets list count

      eventAttendees

      Event attendees list count

      p2pRegistrations

      P2P event registrations list count

      p2pFundraiserSummary

      P2P event fundraiser summary count

      p2pTeams

      P2P event teams list count

      p2pPurchases

      P2P event purchases list count

      fundraiserMetadata

      P2P event fundraiser metadata count

      teamMetadata

      P2P event team metadata count

       

      Example

      Curl

      curl -H "authToken:$AUTHTOKEN" 
      https://dev-api.salsalabs.org/api/developer/ext/v1/metrics

      Output 

      {
        "id""8a9aa3a2-083a-4826-88e8-a292d5af1f25",
        "timestamp""2018-02-02T15:14:07.027Z",
        "header": {
          "processingTime": 64,
          "serverId""ignite-small3.lab.salsalabs.net"
        },
        "payload": {
          "rateLimit": 300,
          "totalAPICalls": 0,
          "currentRateLimit": 0,
          "lastAPICall": 0,
          "totalAPICallFailures": 0,
          "activityFormTypeList": 0,
          "activityFormList": 0,
          "blastList": 0,
          "activityMetadata": 0,
          "activitySummary": 0,
          "targetedActionTargets": 0,
          "eventAttendees": 0
        }

       

       

       

      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Please sign in to leave a comment.