apiary.apib

FORMAT: 1A
HOST: http://inttest.apiblueprint.org/

# int API

It's Ninja Time application API

## Events Collection [/api/events/{eventid}]

+ Parameters
    + eventid (number) - Unique identifier of the event

### List all events [GET /api/events]

+ Response 200 (application/json)
    + Attributes (EventList)

### Get a single event [GET /api/events/{eventid}]

+ Response 200 (application/json)
    + Attributes (EventDetail)

+ Response 404

### Modify event details [PUT /api/events/{eventid}]

+ Request (application/json)
    + Attributes (EventDetailUpdate)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Start an event [POST /api/events/{eventid}/start]

+ Response 200 (application/json)
    + Attributes (StartStageResponse)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

## Event Obstacle Collection [/api/events/{eventid}/obstacles]

+ Parameters
    + eventid (number) - Unique identifier of the event

### Add an event obstacle [POST /api/events/{eventid}/obstacles]

+ Request (application/json)
    + Attributes (EventObstacleCreate)

+ Response 200 (application/json)
    + Attributes (EventObstacleCreateResponse)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Modify an event obstacle [PUT /api/events/{eventid}/obstacles/{obstacleid}]

+ Parameters
    + obstacleid (number) - Unique identifier of the obstacle

+ Request (application/json)
    + Attributes (EventObstacleModify)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Remove an event obstacle [DELETE /api/events/{eventid}/obstacles/{obstacleid}]

+ Parameters
    + obstacleid (number) - Unique identifier of the obstacle

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

## Event Participant Collection [/api/events/{eventid}/participants]

+ Parameters
    + eventid (number) - Unique identifier of the event

### Add an event participant [POST /api/events/{eventid}/participants]

+ Request (application/json)
    + Attributes (EventParticipantCreate)

+ Response 200 (application/json)
    + Attributes (EventParticipantCreateResponse)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Modify an event participant [PUT /api/events/{eventid}/participants/{participantid}]

+ Parameters
    + participantid (number) - Unique identifier of the participant in the event

+ Request (application/json)
    + Attributes (EventParticipantModify)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Remove an event participant [DELETE /api/events/{eventid}/participants/{participantid}]

+ Parameters
    + participantid (number) - Unique identifier of the participant in the event

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

## Stages Collection [/api/events/{eventid}/stages/{stageid}]

+ Parameters
    + eventid (number) - Unique identifier of the event
    + stageid (number) - Unique identifier of the stage

### Get a single stage [GET /api/events/{eventid}/stages/{stageid}]

+ Response 200 (application/json)
    + Attributes (StageDetail)

+ Response 404

### Get missing participants [GET /api/events/{eventid}/stages/{stageid}/missingparticipants]

+ Response 200 (application/json)
    + Attributes (StageMissingParticipants)

+ Response 404

### Add a stage [POST /api/events/{eventid}/stages]

API will automatically create, order, and name the stage based on standards.

+ Response 200 (application/json)
    + Attributes (EventStage)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Modify a stage [PUT /api/events/{eventid}/stages/{stageid}]

+ Request (application/json)
    + Attributes (EventStageModify)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Remove a stage [DELETE /api/events/{eventid}/stages/{stageid}]

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### End a live stage [POST /api/events/{eventid}/stages/{stageid}/finish]

+ Request (application/json)
    + Attributes (EndStageParticipantList)

+ Response 200 (application/json)
    + Attributes (StartStageResponse)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Reorder upcoming runs in a live stage [POST /api/events/{eventid}/stages/{stageid}/order]

+ Request (application/json)
    + Attributes (StageReorderRequest)

+ Response 200 (application/json)
    + Attributes (StageDetail)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

## Stage Obstacles Collection [/api/events/{eventid}/stages/{stageid}/obstacles]

+ Parameters
    + eventid (number) - Unique identifier of the event
    + stageid (number) - Unique identifier of the stage

### List all stage obstacles [GET /api/events/{eventid}/stages/{stageid}/obstacles]

+ Request (application/json)

+ Response 200 (application/json)
    + Attributes (StageObstacleList)

+ Response 404

### Add obstacle to stage [POST /api/events/{eventid}/stages/{stageid}/obstacles]

+ Request (application/json)
    + Attributes (StageObstacleAdd)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Modify obstacle order in stage [PUT /api/events/{eventid}/stages/{stageid}/obstacles/{obstacleid}]

+ Parameters
    + obstacleid (number) - Unique identifier of the obstacle in this event

+ Request (application/json)
    + Attributes (StageObstacleReorder)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Remove stage obstacle [DELETE /api/events/{eventid}/stages/{stageid}/obstacles/{obstacleid}]

+ Parameters
    + obstacleid (number) - Unique identifier of the obstacle in this event

+ Response 200 (application/json)
    + Attributes (StageObstacleList)

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

## Stage Results Collection [/api/events/{eventid}/stages/{stageid}/results]

+ Parameters
    + eventid (number) - Unique identifier of the event
    + stageid (number) - Unique identifier of the stage

### List current stage results [GET /api/events/{eventid}/stages/{stageid}/results]

+ Request (application/json)

+ Response 200 (application/json)
    + Attributes (EventStageResultList)

+ Response 404

### Record a single stage result [POST /api/events/{eventid}/stages/{stageid}/results/{runid}]
+ Parameters
    + runid (number) - Unique identifier of this run result

+ Request (application/json)
    + Attributes (RecordStageResult)

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

### Remove a single stage result [DELETE /api/events/{eventid}/stages/{stageid}/results/{runid}]
+ Parameters
    + runid (number) - Unique identifier of this run result

+ Response 204

+ Response 400 (application/json)
    + Attributes (Error400)

+ Response 404

# Data Structures

## EventList (object)
- Events (array[EventSummary])

## EventSummary (object)
- EventId: 5 (number) - Unique Id of the event
- Name: `Sample Ninja Event` (string) - Viewed name of event
- StartDate: `2018-10-10 9:00 am` (string) - Date and time when the event starts
- Location: `Sample Location` (string) - Free text location description
- Description: `Sample Description` (string) - Free text to describe anything else about your event
- ParticipantCount: 20 (number) - How many participants we currently have
- StageCount: 4 (number) - Total count of stages
- ActiveStageId: 9 (number) - Unique Id of the active stage.  First stage if event is to come.  Null if unstarted or done - see also Completed
- ActiveStageName: `Stage 1` (string) - Name of the ActiveStageId or blank
- Completed: false (boolean) - Has the event been completed?

## EventDetail (object)
- EventSummary (EventSummary)
- ParticipantList (array[EventParticipant])
- StageList (array[EventStage])
- ObstacleList (array[EventObstacle])

## EventDetailUpdate (object)
- Name: `Sample Ninja Event` (string) - Viewed name of event
- StartDate: `2018-10-10 9:00 am` (string) - Date and time when the event starts
- Location: `Sample Location` (string) - Free text location description
- Description: `Sample Description` (string) - Free text to describe anything else about your event

## EventParticipant (object)
- ParticipantId: 4 (number) - Unique Id of the participant in this event
- Name: `Don Thompson` (string) - Name of participant

## StageDetail (object)
- Details (EventStage)
- ObstacleList (array[StageObstacle])
- UpcomingList (array[UpcomingRun])
- FinishedList (array[FinishedRun])

## EventStage (object)
- StageId: 9 (number) - Unique Id of the stage
- StageName: `Stage 1` (string) - Name of the stage.  Typically Stage 1, Stage 2, etc.
- StageOrder: 1 (number) - Numeric order of the stages in the event
- PointsBased: true (boolean) - Is this a points based stage?
- EventId: 5 (number) - Unique Id of the event this stage is part of
- EventName: `Sample Ninja Event` (string) - Viewed name of the event this stage is part of
- ObstacleCount: 6 (number) - Count of obstacles assigned to this stage
- IsLastStage: false (boolean) - Is this the last stage in the event?

## EventObstacle (object)
- ObstacleId: 13 (number) - Unique Id of this obstacle
- Name: `Warped Wall` (string) - Name of this obstacle
- Description: `A very tall curved wall` (string) -  A description of the obstacle

## StageObstacle (object)
- ObstacleId: 13 (number) - Unique Id of this obstacle
- Name: `Warped Wall` (string) - Name of this obstacle
- Order: 1 (number) - Unique Id of the stage this obstacle is part of
- Description: `A very tall curved wall` (string) -  A description of the obstacle

## UpcomingRun (object)
- RunId: 1 (number) - Unique Id of this run
- Participant (EventParticipant) - The participant details
- RunOrder: 6 (number) - Order of this run in the stage - ordered from the beginning of the stage, not the remaining

## RunResultSummary (object)
- NumObstaclesCompleted: 6 (number) - Count of obstacles passed in this result
- RunTime: 84.15 (number) - Total run time to success or failure in seconds.  May include decimal seconds

## FinishedRun (object)
- RunId: 1 (number) - Unique Id of this run
- Participant (EventParticipant) - The participant details
- RunOrder: 6 (number) - Order of this run in the stage - ordered from the beginning of the stage, not the remaining
- Result (RunResultSummary) - Time and number of obstacles finished

## StageResult (object)
- RunId: 42 (number) - Unique Id of this result among all results
- Participant (EventParticipant) - The participant details
- RunOrder: 6 (number) - Order of this run in the stage
- Place: 3 (number) - Finishing place in this stage.  Ordered by number completed descending then time ascending
- Result (RunResultSummary) - Time and number of obstacles finished

## Error400 (object)
- Message: `An error has occurred` (string)

## EventParticipantCreate (object)
- Name: `Don Thompson` (string) - Name of the participant

## EventParticipantModify (object)
- Name: `Don Thompson` (string) - Name of the participant

## EventParticipantCreateResponse (object)
- Participant (EventParticipant)

## EventObstacleCreate (object)
- Name: `Warped Wall` (string) - Short name of the obstacle
- Description: `A very tall curved wall` (string) -  A description of the obstacle

## EventObstacleModify (object)
- Name: `Warped Wall` (string) - Short name of the obstacle
- Description: `A very tall curved wall` (string) -  A description of the obstacle

## EventObstacleCreateResponse (object)
- Obstacle (EventObstacle)

## EventStageModify (object)
- Name: `Stage 1` (string) - Name of the stage.  Typically Stage 1, Stage 2, etc.  Leave null if you do not want to change.
- NewOrder: 1 (number) - New order of the stage if you want to re-order them.  Leave null if you do not want to change.
- PointsBased: true (boolean) - Is this stage scored via points?

## StageObstacleList (object)
- ObstacleList (array[StageObstacle])

## StageObstacleAdd (object)
- ObstacleId: 13 (number) - Unique Id of the event obstacle to add to the stage

## StageObstacleReorder (object)
- NewOrder: 3 (number) - New order of this obstacle in the stage.  The old obstacle at this position and all other are pushed down by one.  First obstacle is 1.

## StartStageResponse (object)
- StageId: 1 (number) - The unique identifier of the stage now active for this event.

## EndStageParticipantList (object)
- ParticipantList (array[number]) - An array of EventParticipant unique identifiers for the participants who will move on to the next stage.  When finishing the last stage, this value will be ignored and can be null.

## EventStageResultList (object)
- Details (EventStage)
- ResultList (array[StageResult])

## StageReorderRequest (object)
- Method: 'random' (string) - String of the method to use in reordering.  Reorders only apply to participants not yet finished.  Options are:  'random', 'first', 'reverse', 'manual'
- ParticipantList (array[number]) - Only used if method is 'manual'.  An ordered array of event participant ids to cause a re-order for the event.  Will ignore any changes to participants with results for this stage.

## ObstacleResult (object)
- ObstacleId: 9 (number) - Unique identifier of the obstacle in the stage
- Attempted: true (boolean) - Was the obstacle attempted?
- Completed: true (boolean) - Was the obstacle completed successfully?
- TimeToFinish: 84.15 (number) - Time in seconds to complete this obstacle since the beginning of the run.  Timed in fractional seconds.

## RecordStageResult (object)
- StartLocalTime: `2018-10-10 10:13:28 am` - Local time from the timing device when the run started.
- ObstacleResultList (array[ObstacleResult]) - Array of results for each obstacle in the stage

## StageMissingParticipants (object)
- ParticipantList (array[EventParticipant])