Participants - Hip-Hop-Xpress/hhx-api GitHub Wiki

Participants

Guide

The Participant object

Each participant object holds data in JSON format. All attributes are required in POST requests, but not in PUT requests (see more here).

{
  "id": 0,
  "name": "Joe Bolton",
  "description": [
    "Joe Bolton grew up in Champaign, IL, and participated in activies at the Don...",
    "Some of his work is featured in an exhibit at...",
  ],
  "images": [
    {
      "url":"https://publish.illinois.edu/.../WillJoeBoomBoxBuild-300x225.jpg",
      "caption":"Joe Bolton on the right, showing a youth how to build a speaker in 2018."
    },
    {
      "url":"https://publish.illinois.edu/.../JoeBolton_YFeb2020-300x225.jpeg",
      "caption":"Display of Joe Bolton’s work, Art @ the Y"
    }
  ]
}

Attributes

Name Type Restrictions Description
id number must be unique non-zero integer, cannot be updated once created unique identifier for participant
name string must be non-empty display name for participant
description Array of string must be non-empty describes the participant
images Array of Image Objects must be non-empty, exactly one Image Object must have componentImage set to true lists all display images for participant

The Participant 'Image' object

Image description for images array in the participant object. Each field is required when creating new images.

{
  "url": "https://publish.illinois.edu/.../IPoweredTrailer.jpg",
  "caption": "",
}

Attributes

Name Type Restrictions Description
url string must be a valid URL points to image of participant
caption string none, can be empty briefly describes the image

Endpoints

Overview

A quick overview of all endpoints related to Participants on the Hip Hop Xpress

   POST /v1/participants
    GET /v1/participants

    GET /v1/participants/:id
    PUT /v1/participants/:id
 DELETE /v1/participants/:id

   POST /v1/participants/:id/images
    GET /v1/participants/:id/images

   POST /v1/participants/:id/description
    GET /v1/participants/:id/description

Usage

All use cases for the Participants endpoints are listed below.

Collection wide:

Participant specific:

Participant data specific:

View the error documentation for what to expect if your request fails.

Create participant

POST /v1/participants

Creates a participant by including a participant object (JSON) in the request body. All fields are required, and the id must be a unique, non-negative integer.

Parameters

A valid participant object (JSON) with correct attributes

Returns

The participant object as added in the database if successful

Retrieve all participants

GET /v1/participants

Retrieves the data for all participants

Parameters

None

Returns

An array of all participant objects

Retrieve participant

GET /v1/participants/:id

Retrieves a specific participant through its id

Parameters

None

Returns

The participant object with specified id

Update participant

PUT /v1/participants/:id

Updates attributes of a specified participant object by id

Parameters

A participant object containing only the attributes needing change, and their updated values. For example, if you need to change the date attribute, you only need to include the date field in your request: {"name": "some new name"}. However, any updated attributes must follow the attribute restrictions.

Returns

The updated participant object

Delete participant

DELETE /v1/participants/:id

Deles a participant object with id

Parameters

None

Returns

The participant object that was deleted

Add images

POST /v1/participants/:id/images

Adds images to a specific participant by including the image objects in your request body.

Parameters

Either a single image object or an array of image objects in the request body. All attributes are required for each image object.

Returns

The updated images array

Retrieve images

GET /v1/participants/:id/images

Retrieves all the images for a specified participant by id

Parameters

None

Returns

The images array of participant with specified id

Add to description

POST /v1/participants/:id/description

Adds text to a participant's description by by including the text in the request body

Parameters

Either a single string or an array of strings in the request body

Returns

The updated description (array of strings)t

Retrieve description

GET /v1/participants/:id/description

Retrieves all the text in a specific participant's description

Parameters

None

Returns

The description (array of strings)

Back to top