#%RAML 0.8
title: Communication API
baseUri: https://api.us1.covisint.com/communication/v1
protocols:
- HTTPS
schemas:
- resourceReferences: "{\n  \"id\" : \"http://api.covisint.com/schema/resourceReferences\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"description\"
    : \"Collection of broadcast templates\",\n  \"type\" : \"array\",\n  \"items\"
    :  { \n    \"$ref\": \"http://api.covisint.com/schema/resourceReference#\"\n  }\n}\n"
- resourceReference: |
    {
      "id" : "http://api.covisint.com/schema/resourceReference",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "description" : "Schema representing links",
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "string",
          "maxLength" : 36,
          "description" : "The unique identifier for the resource.",
          "required": true
        },
        "type" : {
          "type" : "string",
          "description" : "The type of the resource."
        },
        "realm" : {
          "type" : "string",
          "description" : "The realm of the resource."
        }
      }
    }
- namedResourceReference: "{\n  \"id\" : \"http://api.covisint.com/schema/namedScopedResource\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Expands on the basic resource reference and adds internationalized
    name and description.\",\n  \"extends\" : {\n        \"$ref\" : \"http://api.covisint.com/schema/resourceReference#\"\n
    \ },\n  \"properties\" : {\n     \"name\" : {  \n       \"description\": \"Internationalized
    resource name.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    },\n     \"description\" : {  \n       \"description\": \"Internationalized
    resource description.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    }\n   }\n}\n"
- resource: "{\n  \"id\" : \"http://api.covisint.com/schema/resource\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Core schema\",\n
    \ \"definitions\" : {\n    \"resource\" : {\n      \"id\" : \"resource\",\n      \"type\"
    : \"object\",\n      \"description\" : \"A basic resource.\",\n      \"properties\"
    : {\n        \"id\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The unique identifier for this resource.\",\n
    \         \"required\": true\n        },\n        \"version\": {\n          \"type\"
    : \"number\",\n          \"minimum\" : 0,\n          \"maximum\" : 9223372036854775807,\n
    \         \"description\" : \"The current version for this resource.  Exists once
    the resource has been saved. This is mandatory for PUT requests, but should not
    be supplied for POST requests.\",\n          \"required\": false\n        },\n
    \       \"creator\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The creator of this resource. This is mandatory
    if x-requestor header is NOT available\",\n          \"required\": false\n        },\n
    \       \"creatorAppId\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The application id of the creator of this
    resource.\",\n          \"required\": false\n        },\n        \"creation\"
    : {\n          \"type\" : \"number\",\n          \"minimum\" : 0,\n          \"maximum\"
    : 9223372036854775807,\n          \"description\" : \"If this value is provided
    in a POST / PUT request body, it will be ignored and system will generate value
    as time, in milliseconds since the epoch, when this resource was created or upda\",\n
    \         \"required\": false            \n        }\n      }\n    }\n  }\n}\n"
- realmScopedResource: |
    {
      "id" : "http://api.covisint.com/schema/realmScopedResource",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Expands on the base resource and adds a realm attribute.",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "realm" : {
          "type" : "string",
          "maxLength" : 25,
          "pattern" : "^[A-Za-z0-9]{2,25}$",
          "description" : "The realm in which this resource is being created. This is mandatory if x-realm header is NOT available",
          "required": false
        }
      }
    }
- errorResponseSchema: "{\n  \"id\" : \"http://api.covisint.com/schema/errorResponseSchema\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Representation of an HTTP 4xx/5xx error response.\",\n  \"properties\"
    : {\n    \"status\" : { \n      \"type\" : \"number\",\n      \"minimum\" : 400,\n
    \     \"maximum\" : 599,\n      \"description\" : \"The HTTP status code.\",\n
    \     \"required\": true\n    },\n    \"apiMessage\" : { \n      \"type\" : \"string\",\n
    \     \"description\" : \"A helpful, human-readable description of the error,
    useful for basic diagnostics.\" \n    },\n    \"apiStatusCode\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"The API-specific status code.\"\n    }\n\n
    \ }\n}\n"
- serviceCode: "{\n  \"id\" : \"http://api.covisint.com/schema/serviceCodes\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\": \"object\",\n  \"description\":
    \"The site/service/location codes granted along with a service.\",\n  \"properties\":
    {\n    \"code\": { \"type\": \"string\", \"required\": true, \"maxLength\": 200,
    \"description\": \"The code value.\" },\n    \"codeKind\": { \"type\": \"string\",
    \"required\": true, \"maxLength\": 36, \"description\": \"The associated business
    unit.\" }\n  }\n}     \n"
- serviceCodes: "{\n  \"type\" : \"array\",\n  \"description\" : \"The site/service/location
    codes granted along with the service, if any.\",\n  \"items\" : { \"$ref\" : \"http://api.covisint.com/schema/serviceCode#\"},\n
    \ \"required\": false\n}\n\n        \n"
- internationalString: |
    {
      "id": "http://api.covisint.com/idm/schema/internationalString",
      "$schema": "http://json-schema.org/draft-04/schema",
      "type": "array",
      "description" : "An internationalized string value, supporting one or more language translations.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "lang": { "type": "string", "maxLength": 10, "description": "The language or locale in which the text is written." },
          "text": { "type": "string", "maxLength": 2000, "description": "The internationalized text value." }
        }
      }
    }
- communications: "{\n  \"id\" : \"http://api.covisint.com/schema/communications\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"description\"
    : \"Collection of communications\",\n  \"type\" : \"array\",\n  \"items\" :  {
    \n    \"$ref\": \"http://api.covisint.com/schema/communication#\"\n  }\n}\n"
- communication: "{\n  \"id\" : \"http://api.covisint.com/schema/communication\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Schema representing a communication\",\n  \"extends\" :
    {\n        \"$ref\" : \"http://api.covisint.com/schema/realmScopedResource#\"\n
    \ },\n  \"properties\" : {            \n    \"lang\" : {\n      \"description\":
    \"TThe language of the communication.\",\n      \"required\": true,\n      \"type\":\"string\",\n
    \     \"maxLength\" : 255\n    },\n    \"from\" : {\n      \"description\": \"The
    sender of the communication, in reader-friendly form.\",\n      \"required\":
    true,\n      \"type\":\"string\",\n      \"maxLength\" : 255\n    },\n    \"type\"
    : {\n      \"description\": \"The type of communication\",\n      \"required\":
    true,\n      \"type\":\"string\",\n      \"maxLength\" : 255\n    },\n    \"shortText\"
    : {\n      \"description\": \"The short text of the communication.\",\n      \"required\":
    false,\n      \"type\":\"string\",\n      \"maxLength\" : 1000\n    },\n    \"fullText\"
    : {\n      \"description\": \"The full text of the communication.\",\n      \"required\":
    false,\n      \"type\":\"string\",\n      \"maxLength\" : 4000\n    },\n    \"fullTextMediaType\"
    : {\n      \"description\": \"The media type of the full text.\",\n      \"required\":
    false,\n      \"type\":\"string\",\n      \"maxLength\" : 255\n    },\n    \"mobileService\"
    : {\n      \"description\": \"The id of the mobile service that the communication
    is related to.\",\n      \"required\": false,\n      \"type\":\"string\",\n      \"maxLength\"
    : 255\n    },\n    \"pushData\" : {\n      \"description\": \"The text to be sent
    to a push target.\",\n      \"required\": false,\n      \"type\":\"string\",\n
    \     \"maxLength\" : 255\n    },\n    \"sourceReference\" : {\n      \"description\":
    \"The reference that the sender can set for tracking purposes.\",\n      \"required\":
    false,\n      \"type\":\"string\",\n      \"maxLength\" : 255\n    },\n    \"broadcast\"
    : {\n      \"description\": \"The related Broadcast ID.\",\n      \"required\":
    true,\n      \"$ref\" : \"http://api.covisint.com/schema/resourceReferences#\"\n
    \   },\n    \"persons\" : {\n      \"description\": \"The users to receive the
    communication.\",\n      \"required\": true,\n      \"$ref\" : \"http://api.covisint.com/schema/resourceReferences#\"\n
    \   }\n  }\n}\n"
- messages: "{\n  \"id\" : \"http://api.covisint.com/schema/messages\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Collection
    of messages\",\n  \"type\" : \"array\",\n  \"items\" :  { \n    \"$ref\": \"http://api.covisint.com/schema/message#\"\n
    \ }\n}\n"
- message: "{\n  \"id\" : \"http://api.covisint.com/schema/message\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n  \"description\"
    : \"Schema representing a message\",\n  \"extends\" : {\n        \"$ref\" : \"http://api.covisint.com/schema/realmScopedResource#\"\n
    \ },\n  \"properties\" : {            \n    \"isNotification\" : {\n      \"description\":
    \"Whether this message is a notification or not.\",\n      \"required\": false,\n
    \     \"type\":\"boolean\"\n    },\n    \"status\" : {\n      \"description\":
    \"The status of the message.\",\n      \"required\": false,\n      \"type\":\"string\",\n
    \     \"maxLength\" : 255\n    },\n    \"processed\" : {\n      \"description\":
    \"The instant the message was queued to the target.\",\n      \"required\": false,\n
    \     \"type\":\"number\",\n      \"minimum\" : 0,\n      \"maximum\" : 9223372036854775807\n
    \   },\n    \"statusMessage\" : {\n      \"description\": \"The message associated
    with generating and queuing the message.\",\n      \"required\": false,\n      \"type\":\"string\",\n
    \     \"maxLength\" : 4000\n    },\n    \"type\" : {\n      \"description\": \"The
    mssage target type.\",\n      \"required\": true,\n      \"type\":\"string\",\n
    \     \"maxLength\" : 255\n    },\n    \"communication\" : {\n      \"description\":
    \"The communication associcated with the message.\",\n      \"required\": true,\n
    \     \"$ref\" : \"http://api.covisint.com/schema/communications#\"\n    },\n
    \   \"targetId\" : {\n      \"description\": \"TThe target of the message.\",\n
    \     \"required\": true,\n      \"$ref\" : \"http://api.covisint.com/schema/resourceReferences#\"\n
    \   }\n  }\n}\n"
traits:
- secured:
    usage: Apply this to any method that needs to be secured
    description: Requests requires authentication using a bearer token.
    headers:
      Authorization:
        description: Access token that is obtained from the /token endpoint of the
          oauth API.
        pattern: "^Bearer .*$"
        example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk
        required: true
    responses:
      401:
        description: Unauthenticated request.  This is returned if the access token
          is missing, invalid, or expired.  Access tokens are obtained through the
          /token endpoint of the Oauth API.
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      403:
        description: Unauthorized request.  The requestor is not authorized to perform
          the requested operation.
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
- getResponse:
    responses:
      404: &3
        description: |
          The URI requested is invalid or the resource requested does not exist.
          ___
          Substatus codes and error messages are mentioned below:
          + (If a resource id is a URI parameter) framework:resource:missing - A resource with the following ID was not found: {resourceId}
          + No message for an invalid URI
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      406: &1
        description: |
          Unable to produce content of specified 'Accept' media type
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request:unsupported:mediatype - The server is unable to produce content of type {acceptMediaType}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      500: &2
        description: |
          An unknown server error occurred
          ___
          Substatus codes and error messages are mentioned below:
          + framework:unknown
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
- getSearchResponse:
    responses:
      406: *1
      500: *2
- postResponse:
    responses:
      406: *1
      415: &4
        description: |
          Unable to consume content of specified 'Content-Type' media type
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request:unsupported:mediatype - The server is unable to consume content of type {contentMediaType}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      500: *2
- deleteResponse:
    responses:
      500: *2
- putResponse:
    responses:
      404: *3
      406: *1
      409: &5
        description: |
          There is a conflict in identifying the resource being acted on.  There are two categories.  (1) The unique identifier in the URL and in the body are different.  (2) The current version of the resource being updated and the version sent in the body of the request. This may be an indication that the resource has changed since the client loaded it. The conflict should be resolved and the update resubmitted with the current version of the resource.
          + framework:resource:conflict
          + framework:resource:conflict:id - The ID of the resource in the request, {requestedId}, does not match the ID of the given resource, {resourceId}
          + framework:resource:conflict:version - The version of the provided resource, {requestVersion}, does not match the current version of the resource, {latestVersion}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      415: *4
      500: *2
- putCreateResponse:
    responses:
      406: *1
      409: *5
      415: *4
      500: *2
- pagableRequest:
    queryParameters:
      page:
        description: Which page to return in the paginated results.  The first page
          is page 1.
        type: integer
        required: false
        minimum: 1
        default: 1
      pageSize:
        description: How many items per page in the paginated results.
        type: integer
        required: false
        minimum: 1
        default: 50
        maximum: 200
"/communication":
  is:
  - secured
  description: Collection endpoint for communication.
  get:
    is:
    - getSearchResponse
    - pagableRequest
    description: Search communication based on the given filter parameters.
    headers:
      Accept:
        description: Media type.
        example: application/vnd.com.covisint.platform.communication.v1+json
        type: string
        required: true
    queryParameters:
      personId:
        description: Retrieve only communication with the specified person Id. Multiple
          parameters are supported and the search results will be a union.
        type: string
        required: false
    responses:
      200:
        description: All communications that satisfy the query parameters were successfully
          retrieved (response collection may be empty).
        body:
          application/vnd.com.covisint.platform.communication.v1+json:
            schema: communication
      400:
        description: |
          There was a problem with the client's request
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request
          + framework:request:io
          + framework:request:io:read - Invalid input. There was an error while parsing.
          + framework:request:io:read:parsing
          + framework:request:io:write
          + framework:request:header:missing - Missing request header: {headerName}
          + framework:request:param:missing - Missing request parameter: {queryParameterName}
          + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}
          + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  post:
    is:
    - postResponse
    description: Creates a new communication.
    headers:
      Accept:
        description: Media type.
        example: application/vnd.com.covisint.platform.communication.v1+json
        type: string
        required: true
    body:
      application/vnd.com.covisint.platform.communication.v1+json:
        schema: communication
    responses:
      201:
        description: A new communication was created.
        body:
          application/vnd.com.covisint.platform.communication.v1+json:
            schema: communication
      400:
        description: |
          There was a problem with the client's request
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request
          + framework:request:io
          + framework:request:io:read - Invalid input. There was an error while parsing.
          + framework:request:io:read:parsing
          + framework:request:io:write
          + framework:request:header:missing - Missing request header: {headerName}
          + framework:request:param:missing - Missing request parameter: {queryParameterName}
          + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}
          + framework:request:data:invalid - The following information should not be part of the resource: {resourceFieldName}
          + framework:resource:data:illegal - The following information was illegal from the resource:  {fieldSpecificError(s)}
          + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]
          + communication.message.target - No valid message target found for person id
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  "/{communicationId}":
    description: Endpoint for a communication.
    uriParameters: 
    is:
    - secured
    get:
      is:
      - getResponse
      description: Returns a communication by its unique identifier.
      headers:
        Accept:
          description: Media type.
          example: application/vnd.com.covisint.platform.communication.v1+json
          type: string
          required: true
      responses:
        200:
          description: The communication was successfully retrieved.
          body:
            application/vnd.com.covisint.platform.communication.v1+json:
              schema: communication
        400:
          description: "There was a problem with the client's request\n___\nSubstatus codes are mentioned below:\n+ framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application] \n"
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema
    delete:
      is:
      - deleteResponse
      description: Deletes a communication.
      headers: 
      responses:
        204:
          description: The communication was successfully deleted.
        400:
          description: |
            There was a problem with the client's request
            ___
            Substatus codes are mentioned below:
            + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema
"/messages":
  is:
  - secured
  description: Collection endpoint for message.
  get:
    is:
    - getSearchResponse
    - pagableRequest
    description: Search message based on the given filter parameters.
    headers:
      Accept:
        description: Media type.
        example: application/vnd.com.covisint.platform.message.v1+json
        type: string
        required: true
    queryParameters:
      communicationId:
        description: Retrieve only message with the specified communication Id. Multiple
          parameters are supported and the search results will be a union.
        type: string
        required: false
    responses:
      200:
        description: All messages that satisfy the query parameters were successfully
          retrieved (response collection may be empty).
        body:
          application/vnd.com.covisint.platform.message.v1+json:
            schema: message
      400:
        description: |
          There was a problem with the client's request
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request
          + framework:request:io
          + framework:request:io:read - Invalid input. There was an error while parsing.
          + framework:request:io:read:parsing
          + framework:request:io:write
          + framework:request:header:missing - Missing request header: {headerName}
          + framework:request:param:missing - Missing request parameter: {queryParameterName}
          + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}
          + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  post:
    is:
    - postResponse
    description: Creates a new message.
    headers:
      Accept:
        description: Media type.
        example: application/vnd.com.covisint.platform.message.v1+json
        type: string
        required: true
    body:
      application/vnd.com.covisint.platform.message.v1+json:
        schema: message
    responses:
      201:
        description: A new message was created.
        body:
          application/vnd.com.covisint.platform.message.v1+json:
            schema: message
      400:
        description: "There was a problem with the client's request\n___\nSubstatus codes and error messages are mentioned below:\n+ framework:request\n+ framework:request:io\n+ framework:request:io:read - Invalid input. There was an error while parsing.\n+ framework:request:io:read:parsing\n+ framework:request:io:write\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:param:missing - Missing request parameter: {queryParameterName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:data:invalid - The following information should not be part of the resource: {resourceFieldName}\n+ framework:resource:data:illegal - The following information was illegal from the resource:  {fieldSpecificError(s)}\n+ framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]\n+ message.target - The message target with id (targetId) does not exist\n+ message.target.manager.invalid - No target manager defined for the target type (targetType) \n"
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  "/{messageId}":
    description: Endpoint for a message.
    uriParameters: 
    is:
    - secured
    get:
      is:
      - getResponse
      description: Returns a message by its unique identifier.
      headers:
        Accept:
          description: Media type.
          example: application/vnd.com.covisint.platform.message.v1+json
          type: string
          required: true
      responses:
        200:
          description: The message was successfully retrieved.
          body:
            application/vnd.com.covisint.platform.message.v1+json:
              schema: message
        400:
          description: "There was a problem with the client's request\n___\nSubstatus codes are mentioned below:\n+ framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application] \n"
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema
    delete:
      is:
      - deleteResponse
      description: Deletes a message.
      headers: 
      responses:
        204:
          description: The message was successfully deleted.
        400:
          description: |
            There was a problem with the client's request
            ___
            Substatus codes are mentioned below:
            + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application]
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema