OSU Events API

This API provides management of events for Oregon State University. It also allows for retrieval of event types, event topics, locations, counties, campuses, departments, and audiences.

Endpoints

This section will provide a basic description of all endpoints. For a more detailed blueprint of this API, please see the swagger specification.

GET

/events:

Gets all events.

/events/{eventID}

Gets a single event by its ID.

/event-types

Gets all event types.

/event-types/{eventTypeID}

Gets a single event type by its ID.

/event-topics

Gets all event topics.

/event-topics/{eventTopicID}

Gets a single event topic by its ID.

/locations

Gets a paginated list of locations. Page number and size can be passed as parameters.

/locations/{locationID}

Gets a single location by its ID.

/counties

Gets all counties.

/counties/{countyID}

Gets a single county by its ID.

/campuses

Gets a paginated list of campuses. Page number and size can be passed as parameters.

/campuses/{campusID}

Gets a single campus by its ID.

/departments

Gets a paginated list of departments. Page number and size can be passed as parameters.

/departments/{departmentID}

Gets a single department by its ID.

/audiences

Gets all audiences.

/audiences/{audienceID}

Gets a single audience by its ID.

POST

/events

Creates an event specified by a result object in the body of a request. Since an ID will be generated by the server, the id field is not required and any value in this field will be ignored.

Valid example of body:

{
    "data": {
        "id": "null",
        "type": "events",
        "attributes": {
            "title": "Example Event",
            "description": "This is an example event.",
            "locationID": null,
            "otherLocationName": "Alternate location name",
            "room": "Example room",
            "address": "Example address",
            "city": "Corvallis",
            "state": "Oregon",
            "countyIDs": null,
            "campusID": null,
            "eventURL": "www.eventurl.com",
            "photoURL": "http://communications.oregonstate.edu/sites/communications.oregonstate.edu/files/beaverlogo_primary_v4.png",
            "ticketURL": "www.ticketurl.com",
            "ticketCost": "$100",
            "hashtag": "examplehashtag",
            "keywords": null,
            "tags": null,
            "allowsReviews": false,
            "allowUserActivity": true,
            "departmentIDs": null,
            "contactName": "Contact Name",
            "contactEmail": "contact@contact.com",
            "contactPhone": "111-111-1111",
            "eventTypeIDs": null,
            "eventTopicIDs": null,
            "audienceIDs": null,
            "visibility": null,
            "instances": [
                {
                    "start": "2018-12-02T21:15:00Z",
                    "end": "2018-12-02T21:30:00Z"
                },
                {
                    "start": "2018-12-04T00:15:00Z",
                    "end": "2018-12-04T00:30:00Z"
                }
            ]
        }
    }
}

PUT

/events/{eventID}

Updates an event specified by its ID in the path and a result object in the body of the request. Since the ID of the event will not change, the id field is not required and any value in this field will be ignored. The body of a PUT request should follow the same format as the body of a POST request

DELETE

/events/{eventID}

Deletes an event specified by its ID.

Updating the Cache

This API maintains a local cache of custom data from the vendor calendar system. The cache should be updated on a regular basis to ensure the data validation specific to the /events resources is accurate. Doing a PUT request to these endpoints will update their respective cache.

• Custom Fields /cache/update/customfields
• Departments /cache/update/departments
• Filters /cache/update/filters
• Groups /cache/update/groups
• Places /cache/update/places

Skeleton

This API is based on the Web API Skeleton. This section covers steps related to the skeleton required to build and run the API.

Generate Keys

HTTPS is required for Web APIs in development and production. Use keytool(1) to generate public and private keys.

Generate key pair and keystore:

$ keytool \
    -genkeypair \
    -dname "CN=Jane Doe, OU=Enterprise Computing Services, O=Oregon State University, L=Corvallis, S=Oregon, C=US" \
    -ext "san=dns:localhost,ip:127.0.0.1" \
    -alias doej \
    -keyalg RSA \
    -keysize 2048 \
    -sigalg SHA256withRSA \
    -validity 365 \
    -keystore doej.keystore

Export certificate to file:

$ keytool \
    -exportcert \
    -rfc \
    -alias "doej" \
    -keystore doej.keystore \
    -file doej.pem

Import certificate into truststore:

$ keytool \
    -importcert \
    -alias "doej" \
    -file doej.pem \
    -keystore doej.truststore

Gradle

This project uses the build automation tool Gradle. Use the Gradle Wrapper to download and install it automatically:

$ ./gradlew

The Gradle wrapper installs Gradle in the directory ~/.gradle. To add it to your $PATH, add the following line to ~/.bashrc:

$ export PATH=$PATH:/home/user/.gradle/wrapper/dists/gradle-2.4-all/WRAPPER_GENERATED_HASH/gradle-2.4/bin

The changes will take effect once you restart the terminal or source ~/.bashrc.

Tasks

List all tasks runnable from root project:

$ gradle tasks

IntelliJ IDEA

Generate IntelliJ IDEA project:

$ gradle idea

Open with File -> Open Project.

Configure

Copy configuration-example.yaml to configuration.yaml. Modify as necessary, being careful to avoid committing sensitive data.

Build

Build the project:

$ gradle build

JARs will be saved into the directory build/libs/.

Run

Run the project:

$ gradle run