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 |
---|---|
|
Retrieve a resource |
|
Create a new resource |
|
Update resource |
|
Partially update resource |
|
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 |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
|
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 |
---|---|---|
|
|
The message contained in the exception. |
|
|
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.
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 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"
}
}
}
Links
Relation | Description |
---|---|
|
Link to notificationSystems |
|
Link to publishers |
|
Link to notificationSystems |
|
Link to notificationSystems |
|
Link to users |
Collections
All resource collections have a standard set of links and request parameters used for paging.
Request Parameters
Parameter | Description |
---|---|
|
The page to retrieve |
|
Number of items per page |
Links
Relation | Description |
---|---|
|
The first page of results |
|
The last page of results |
|
The next page of results |
|
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
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
<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. |
||
[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 |
---|---|
|
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 |
---|---|---|
|
|
The ID of the notification |
|
|
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 |
---|---|---|
|
|
The index of the invalid notification in the list. |
|
|
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 |
---|---|---|
|
|
Link to this resource |
|
|
The ID of this notification type |
|
|
Display name of the notification type |
|
|
Priority allowed for this notification type |
|
|
Status of the notification type |
|
|
The text of the notification type |
|
|
Description of the notification type |
|
|
The id of the system that this notification type belongs to |
|
|
"Urgent" priority justification |
|
|
Deliver notifications via Email |
|
|
Deliver notifications via Push |
|
|
Deliver notifications via SMS text messaging |
|
|
Choose the method of SMS text message delivery |
|
|
SMS text message delivery justification |
|
|
The label for the primary action of notifications sent with this type |
|
|
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 |
---|---|
|
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 |
---|---|
|
The version of the resourse. Must be sent back in an |
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 |
---|---|
|
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 |
---|---|
|
The version of the resourse. Must be sent back in an |
|
The URL of the newly created resource |
Response structure
Path | Type | Description |
---|---|---|
|
|
Link to this resource |
|
|
The ID of this notification type |
|
|
Display name of the notification type |
|
|
Priority allowed for this notification type |
|
|
Status of the notification type |
|
|
The text of the notification type |
|
|
Description of the notification type |
|
|
The id of the system that this notification type belongs to |
|
|
"Urgent" priority justification |
|
|
Deliver notifications via Email |
|
|
Deliver notifications via Push |
|
|
Deliver notifications via SMS text messaging |
|
|
Choose the method of SMS text message delivery |
|
|
SMS text message delivery justification |
|
|
The label for the primary action of notifications sent with this type |
|
|
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 to other pages of the collection |
|
|
Number of items in a page |
|
|
Total number of items in the categories collection |
|
|
Number of pages |
|
|
Current page number of the response |
|
|
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 |
---|---|
|
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 |
---|---|---|
|
|
Link to this resource |
|
|
The ID of this system |
|
|
Display name of the system |
|
|
The Id of the publisher for the system |
|
|
Short code for sending SMS text messages |
|
|
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 |
---|---|
|
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 |
---|---|
|
The version of the resourse. Must be sent back in an |
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 |
---|---|
|
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 |
---|---|
|
The version of the resourse. Must be sent back in an |
|
The URL of the newly created resource |
Response structure
Path | Type | Description |
---|---|---|
|
|
Link to this resource |
|
|
The ID of this system |
|
|
Display name of the system |
|
|
The Id of the publisher for the system |
|
|
Short code for sending SMS text messages |
|
|
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
Parameter | Description |
---|---|
|
The user name of the user you wish to query |
Query Parameters
Parameter | Description |
---|---|
|
The unique key of the notification type being queried |
Request Headers
Name | Description |
---|---|
|
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 |
---|---|---|
|
|
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. |
|
|
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. |
|
|
True if the user has an active registered phone number and has indicated their preference to receive SMS messages for the requested type. |