Overview

HTTP verbs

The API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Retrieve a resource

POST

Create a new resource

PUT

Update resource

PATCH

Partially update resource

DELETE

Delete a resource

HTTP status codes

The API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

422 Unprocessable Entity

The submitted resource was invalid. The response body will include an error providing further information

Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. There are two types of errors.

Validation Failures

Validation errors are returned with a 422 Unprocessable Entity status and have the following structure:

{
  "fieldInError": ["list of error messages for this field"],
  "anotherField": ["first error", "second error"]
}

For example, a request that attempts to create a category without a name or icon will produce the following response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 83

{
  "aclExpression" : [ "Required", "Required" ],
  "name" : [ "Must be unique" ]
}

Exceptions and other Failures

Exception errors are returned with other 400 and 500 statuses. The body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

message

String

The message contained in the exception.

type

String

The type of the exception that was thrown.

For example, a request that attempts to update a category without including the version in an If-Match header will produce the following response:

HTTP/1.1 428 Precondition Required
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 143

{
  "type" : "edu.iu.es.esi.cns.api.exception.ETagRequiredException",
  "message" : "A version is required to be sent via an If-Match header"
}

Hypermedia

The API uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

Authentication

Authentication to the APIs is provided through an OAuth2 client credentials mechanism.

OAuth endpoint URL
Access Token:	https://apps.iu.edu/tam-prd/oauth/token?_s=3

To request a client ID and secret for integrating with the API please contact us. We’ll need to know the following information when requesting an account:

  • Email address for notifications related to account expiration

  • The name of your team.

The system administrators will set up an API account for you and forward you the relevant details.

Resources

Index

The index provides the entry point into the service.

Accessing the index

A GET request is used to access the index

GET /rest-api/secure HTTP/1.1
Host: notifications.iu.edu
Response structure
Path Type Description

_links

Object

Links to resources

Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 509

{
  "_links" : {
    "publishers" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/publishers"
    },
    "notificationSystems" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems"
    },
    "notifications" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notifications"
    },
    "notificationTypes" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationTypes"
    },
    "users" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/users"
    }
  }
}
Relation Description

notificationTypes

Link to notificationSystems

publishers

Link to publishers

notificationSystems

Link to notificationSystems

notifications

Link to notificationSystems

users

Link to users

Collections

All resource collections have a standard set of links and request parameters used for paging.

Request Parameters

Parameter Description

page

The page to retrieve

size

Number of items per page

Relation Description

first

The first page of results

last

The last page of results

next

The next page of results

prev

The previous page of results

REST Command Summary

Resource GET POST PUT PATCH DELETE

/{resource path}

List available resources

Create a new resource

-

-

-

/{resource path}/{object ID}

Retrieve object details

-

Update the object in it’s entirety

Partially update the object

Delete the object

Markdown Support

A limited subset of Markdown is supported in one or more API fields in order to provide a minimal amount of text formatting capabilities. Markdown syntax is limited to

Example Input
This is an example text
that contains a hard break,

a [link](http://www.notifications.iu.edu),
and multiple paragraphs.

---
A thematic break above.

* Unordered lists
  1. Ordered lists
  1. _emphasis_ *emphasis*
  1. __strong__ **strong**
* Bullet point
Example Result
<p>This is an example text<br>
  that contains a hard break,</p>
<p>a <a href="http://www.notifications.iu.edu" target="_blank">link</a>, and multiple paragraphs.</p>
<hr>
<p>A thematic break above.</p>
<ul>
 <li>Unordered lists
  <ol>
   <li>Ordered lists</li>
   <li><em>emphasis</em> <em>emphasis</em></li>
   <li><strong>strong</strong> <strong>strong</strong></li>
  </ol></li>
 <li>Bullet point</li>
</ul>
Any HTML tags or entities in the input will be encoded and will be displayed as plain text when viewed in a browser.

Notifications

Create a notification

A POST request will create a new notification.

Request structure

Path Type Description Constraints Valid Values Default Value

[0].title

String

Displays the title of the notification

Required. Must be no longer than 50 characters.

[0].summary

String

A summary of the notification

Must be no longer than 100 characters.

[0].smsDescription

Null

A description of the notification that will be sent in the SMS Text message. If this is not present, the title will be used.

Must be no longer than 400 characters.

[0].description

String

A description of the notification. Markdown is allowed. See Markdown Support for supported syntax.

Required if Summary is not present.

[0].priority

String

The priority of the notification

Required.

NORMAL and URGENT

[0].primaryActionURL

String

The URL for the primary action of the notification

Must be no longer than 2000 characters.

[0].secondaryActionURL

String

The URL for the secondary action of the notification

Must be no longer than 2000 characters.

[0].mobileAppRoute

String

A route inside the IU Mobile application that will be navigated to when a push notification is activated. Needs to be a valid route in IU Mobile app. Contact us if you would like to use this.

Must be no longer than 2000 characters.

[0].notificationType

String

The type of the notification. This must be registered in the application.

Required. Must be no longer than 100 characters.

[0].expirationDate

Number

The date at which the notification becomes eligible for expiration.

By default, a custom expiration date must be more than 24 hours away, and fewer than 30 days away. If configured by the administrator, these times may change. Value is the number of milliseconds since the UNIX epoch.

30 days from creation

[0].replyTo

String

The email address for recipients to reply to.

Must be no longer than 100 characters. Should be a valid email address.

Unless configured otherwise by administrators, it will be a no-reply address.

[0].fromAddress

String

The email address to override the default from address.

Must be no longer than 100 characters. Should be a valid email address. Must be granted permission to use.

notifications@iu.edu

[0].recipients

Array

The user(s) who will receive the notification.

Required.

[0].recipients[0].username

String

The username of the user who will receive this notification.

Must be no longer than 100 characters. A recipient must have only one identifying property, either username, email, or smsNumber.

[0].recipients[0].smsNumber

String

When the valid notification type is chosen, a mobile number can be sent to send a text message to this number.

Must be no longer than 10 characters. A recipient must have only one identifying property, either username, email, or smsNumber. Mobile number must only use digits 0 through 9.

[0].recipients[0].email

String

The email address of the person who will receive this notification.

Must be no longer than 100 characters. A recipient must have only one identifying property, either username, email, or smsNumber.

[0].attachments

Array

List of attachments or files sent in email or downloaded from the notification center.

Can not have more than 5 attachments..

[0].attachments[0].fileName

String

Name of the file with it’s extension (e.g myfile.txt)

Must be no longer than 100 characters. Required.

[0].attachments[0].mimeType

String

Mime or content type of the attachment/file (e.g. text/plain).

Required.

Need to find the valid mime type for your file.

[0].attachments[0].content

String

BASE64 encoded string of your file.

Required. The current maximum size for a file is 5MB.

Example request

POST /rest-api/secure/notifications HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json;version=1
Content-Length: 792
Host: notifications.iu.edu

[ {
  "title" : "title",
  "summary" : "summary",
  "smsDescription" : null,
  "priority" : "NORMAL",
  "description" : "This is an example text  \nthat contains a hard break,\n\na [link](http://www.notifications.iu.edu),\nand multiple paragraphs.",
  "primaryActionURL" : "http://urlToPrimaryActionTaken.edu",
  "secondaryActionURL" : "http://urlToSecondaryActionTaken.edu",
  "mobileAppRoute" : "an/app/route",
  "notificationType" : "Notification_Type",
  "expirationDate" : 1717869877350,
  "replyTo" : "example@example.org",
  "fromAddress" : "from@example.org",
  "recipients" : [ {
    "username" : "user1",
    "email" : null,
    "smsNumber" : null
  } ],
  "attachments" : [ {
    "mimeType" : "text/plain",
    "fileName" : "myFile.txt",
    "content" : "TXkgZmlsZSBjb250ZW50cw=="
  } ]
} ]
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 201 Created
Content-Type: application/hal+json;version=1
Content-Length: 51

[ {
  "notificationId" : 1,
  "title" : "title"
} ]

Response structure

Path Type Description

[0].notificationId

Number

The ID of the notification

[0].title

String

The title of the notification

Validation Failures

When a notification that has been received is not valid, the entire list of notifications is rejected and errors are reported in the response for the items that failed.

Example Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json;version=1
Content-Length: 284

[ {
  "index" : 0,
  "errors" : {
    "fromAddress" : [ "This notification is not allowed to set the from address." ]
  }
}, {
  "index" : 1,
  "errors" : {
    "description" : [ "Required" ],
    "fromAddress" : [ "This notification is not allowed to set the from address." ]
  }
} ]
Response Structure
Path Type Description

[0].index

Number

The index of the invalid notification in the list.

[0].errors

Object

The set of errors on the invalid notification. The structure is as described in Validation Failures

Notification Types

The Notification Types resource is used to list notification types.

Retrieve a notification type

A GET request will retrieve the details of a notification type by the value of the type.

Response structure

Path Type Description

_links.self

Object

Link to this resource

notificationTypeId

Number

The ID of this notification type

name

String

Display name of the notification type

priority

String

Priority allowed for this notification type

status

String

Status of the notification type

notificationType

String

The text of the notification type

description

String

Description of the notification type

notificationSystemId

Number

The id of the system that this notification type belongs to

urgentJustificationNote

String

"Urgent" priority justification

deliveryEmail

Boolean

Deliver notifications via Email

deliveryMobile

Boolean

Deliver notifications via Push

deliverySMS

Boolean

Deliver notifications via SMS text messaging

smsDeliveryType

String

Choose the method of SMS text message delivery

smsJustificationNote

String

SMS text message delivery justification

primaryActionLabel

String

The label for the primary action of notifications sent with this type

secondaryActionLabel

String

The label for the secondary action of notifications sent with this type

Example request

GET /rest-api/secure/notificationTypes/type/my_type HTTP/1.1
Accept: application/hal+json;version=1
Host: notifications.iu.edu
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 200 OK
ETag: W/"0"
Content-Type: application/hal+json;version=1
Content-Length: 661

{
  "notificationTypeId" : 1,
  "name" : "name",
  "priority" : "URGENT",
  "status" : "ACTIVE",
  "notificationType" : "my_type",
  "description" : "description",
  "notificationSystemId" : 1,
  "deliveryEmail" : false,
  "deliveryMobile" : false,
  "deliverySMS" : true,
  "smsDeliveryType" : "STANDARD",
  "urgentJustificationNote" : "Justification for having urgent notifications.",
  "smsJustificationNote" : "Justification for sending SMS text messages.",
  "primaryActionLabel" : "First Action",
  "secondaryActionLabel" : "Second Action",
  "_links" : {
    "self" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationTypes/1"
    }
  }
}
Response Headers
Name Description

ETag

The version of the resourse. Must be sent back in an If-Match header for any PUT or PATCH request

Create a notification type

A POST request will create a new notification type.

Request structure

Path Type Description Constraints Valid Values Default Value

name

String

Display name of the notification type

Required. The following characters are not allowed: []{}()<>|. Must be no longer than 50 characters.

priority

String

Priority allowed for this notification type

Required.

NORMAL and URGENT

status

String

Status of the notification type

Required. Must be ACTIVE

ACTIVE

notificationType

String

The text of the notification type

Required. Must be unique. Must be no longer than 100 characters.

description

String

Description of the notification type

Must be no longer than 100 characters.

notificationSystemId

Number

The id of the system that this notification type belongs to

Required.

urgentJustificationNote

String

"Urgent" priority justification

Required if Urgent Priority is used.

deliveryEmail

Boolean

Deliver notifications via Email

deliveryMobile

Boolean

Deliver notifications via Push

deliverySMS

Boolean

Deliver notifications via SMS text messaging

smsDeliveryType

String

Choose the method of SMS text message delivery

Required if SMS delivery is requested.

STANDARD and ANY

smsJustificationNote

String

SMS text message delivery justification

Required for publishers if SMS delivery is requested.

primaryActionLabel

String

The label for the primary action of notifications sent with this type

Must be no longer than 50 characters.

secondaryActionLabel

String

The label for the secondary action of notifications sent with this type

Must be no longer than 50 characters.

Example request

POST /rest-api/secure/notificationTypes HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json;version=1
Content-Length: 519
Host: notifications.iu.edu

{
  "name" : "name",
  "priority" : "URGENT",
  "status" : "ACTIVE",
  "notificationType" : "my_type",
  "description" : "description",
  "notificationSystemId" : 1,
  "deliveryEmail" : false,
  "deliveryMobile" : false,
  "deliverySMS" : true,
  "smsDeliveryType" : "STANDARD",
  "urgentJustificationNote" : "Justification for having urgent notifications.",
  "smsJustificationNote" : "Justification for sending SMS text messages.",
  "primaryActionLabel" : "First Action",
  "secondaryActionLabel" : "Second Action"
}
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 201 Created
Location: https://notifications.iu.edu/rest-api/secure/notificationTypes/1
ETag: W/"0"
Content-Type: application/hal+json;version=1
Content-Length: 607

{
  "notificationTypeId" : 1,
  "name" : "name",
  "priority" : "URGENT",
  "status" : "ACTIVE",
  "notificationType" : "my_type",
  "description" : "description",
  "notificationSystemId" : 1,
  "deliveryEmail" : false,
  "deliveryMobile" : false,
  "deliverySMS" : true,
  "smsDeliveryType" : "STANDARD",
  "urgentJustificationNote" : "Performed by admin",
  "smsJustificationNote" : "Performed by admin",
  "primaryActionLabel" : "First Action",
  "secondaryActionLabel" : "Second Action",
  "_links" : {
    "self" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationTypes/1"
    }
  }
}
Response Headers
Name Description

ETag

The version of the resourse. Must be sent back in an If-Match header for any PUT or PATCH request

Location

The URL of the newly created resource

Response structure

Path Type Description

_links.self

Object

Link to this resource

notificationTypeId

Number

The ID of this notification type

name

String

Display name of the notification type

priority

String

Priority allowed for this notification type

status

String

Status of the notification type

notificationType

String

The text of the notification type

description

String

Description of the notification type

notificationSystemId

Number

The id of the system that this notification type belongs to

urgentJustificationNote

String

"Urgent" priority justification

deliveryEmail

Boolean

Deliver notifications via Email

deliveryMobile

Boolean

Deliver notifications via Push

deliverySMS

Boolean

Deliver notifications via SMS text messaging

smsDeliveryType

String

Choose the method of SMS text message delivery

smsJustificationNote

String

SMS text message delivery justification

primaryActionLabel

String

The label for the primary action of notifications sent with this type

secondaryActionLabel

String

The label for the secondary action of notifications sent with this type

Notification Systems

Notification systems represent external systems or services that will be sending notifications to the Central Notification Service.

List notification systems

A GET request will list all of the publisher’s notification systems.

Response structure

Path Type Description

_links

Object

Links to other pages of the collection

page.size

Number

Number of items in a page

page.totalElements

Number

Total number of items in the categories collection

page.totalPages

Number

Number of pages

page.number

Number

Current page number of the response

_embedded.notificationSystems

Array

An array of NotificationSystem resources

Example request

GET /rest-api/secure/notificationSystems?page=1&size=1 HTTP/1.1
Accept: application/hal+json;version=1
Host: notifications.iu.edu
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1
Content-Length: 895

{
  "_embedded" : {
    "notificationSystems" : [ {
      "notificationSystemId" : 1,
      "name" : "name",
      "status" : "ACTIVE",
      "publisherId" : 1,
      "smsShortCode" : "12345",
      "_links" : {
        "self" : {
          "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems/1"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems?page=0&size=1"
    },
    "prev" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems?page=0&size=1"
    },
    "next" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems?page=2&size=1"
    },
    "last" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems?page=2&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 3,
    "totalPages" : 3,
    "number" : 1
  }
}

Retrieve a notification system

A GET request will retrieve the details of a publisher’s notification system.

Response structure

Path Type Description

_links.self

Object

Link to this resource

notificationSystemId

Number

The ID of this system

name

String

Display name of the system

publisherId

Number

The Id of the publisher for the system

smsShortCode

String

Short code for sending SMS text messages

status

String

Status of the system

Example request

GET /rest-api/secure/notificationSystems/1000 HTTP/1.1
Accept: application/hal+json;version=1
Host: notifications.iu.edu
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 200 OK
ETag: W/"0"
Content-Type: application/hal+json;version=1
Content-Length: 239

{
  "notificationSystemId" : 1,
  "name" : "name",
  "status" : "ACTIVE",
  "publisherId" : 1,
  "smsShortCode" : "12345",
  "_links" : {
    "self" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems/1"
    }
  }
}
Response Headers
Name Description

ETag

The version of the resourse. Must be sent back in an If-Match header for any PUT or PATCH request

Create a notification system

A POST request will create a new notification system.

Request structure

Path Type Description Constraints Valid Values Default Value

name

String

Display name of the system

Required. Must be unique. The following characters are not allowed: []{}()<>|. Must be no longer than 50 characters.

publisherId

Number

The Id of the publisher for the system

Required.

smsShortCode

String

Short code for sending SMS text messages

Must be no longer than 100 characters.

status

String

Status of the system

Required.

ACTIVE and INACTIVE

Example request

POST /rest-api/secure/notificationSystems HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json;version=1
Content-Length: 93
Host: notifications.iu.edu

{
  "name" : "name",
  "status" : "ACTIVE",
  "publisherId" : 1,
  "smsShortCode" : "12345"
}
Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 201 Created
Location: https://notifications.iu.edu/rest-api/secure/notificationSystems/1
ETag: W/"0"
Content-Type: application/hal+json;version=1
Content-Length: 239

{
  "notificationSystemId" : 1,
  "name" : "name",
  "status" : "ACTIVE",
  "publisherId" : 1,
  "smsShortCode" : "12345",
  "_links" : {
    "self" : {
      "href" : "https://notifications.iu.edu/rest-api/secure/notificationSystems/1"
    }
  }
}
Response Headers
Name Description

ETag

The version of the resourse. Must be sent back in an If-Match header for any PUT or PATCH request

Location

The URL of the newly created resource

Response structure

Path Type Description

_links.self

Object

Link to this resource

notificationSystemId

Number

The ID of this system

name

String

Display name of the system

publisherId

Number

The Id of the publisher for the system

smsShortCode

String

Short code for sending SMS text messages

status

String

Status of the system

Users

The Users resource is used to gather information about users.

Retrieve delivery status

This endpoint allows a publisher to query whether a user is able to receive notifications from a specific notification type.

Example request

GET /rest-api/secure/users/jdoe/delivery-status?type=exampleType HTTP/1.1
Accept: application/hal+json;version=1
Host: notifications.iu.edu
Request Parameters
Path Parameters
Table 1. /rest-api/secure/users/{userName}/delivery-status
Parameter Description

userName

The user name of the user you wish to query

Query Parameters
Parameter Description

type

The unique key of the notification type being queried

Request Headers
Name Description

Accept

application/hal+json is the only supported type. The version specifies which version of the API to use. If version is not provided, the first version is used.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;version=1
Content-Length: 55

{
  "email" : true,
  "push" : false,
  "sms" : false
}

Response structure

Path Type Description

email

Boolean

True if the user has an email address and either has indicated their preference to receive email for the requested type or does not have a preference at all.

push

Boolean

True if the user has an active registered device with IU Mobile and either has indicated their preference to receive push messages for the requested type or does not have a preference at all.

sms

Boolean

True if the user has an active registered phone number and has indicated their preference to receive SMS messages for the requested type.