# The HumorREST API

### API Conventions:

All of the GET requests to the HumorREST Web Service support JSON and XML formats.

The request URL root for GET requests is: http://localhost:8080/HumorREST/api/ followed by one of the following options:

- category/list - returns a list of Humor Categories
- category/{id} - returns a Humor Categories, where {id} is a valid Humor Category Type Id (see below)

- numbered/types - returns a list of Numbered Humor Categories
- numbered/random/{category} - returns a random Numbered Humor record, where {category} is a valid Numbered Humor category
- numbered/specific/{category}/{which} - returns a specific Numbered Humor record, where {category} is a valid Numbered Humor category, and {which} is a specific Numbered Humor record id
- numbered/count/{category} - returns the count of Numbered Humor records, where {category} is a valid Numbered Humor category
- numbered/all/{category} - returns all the Numbered Humor records, where {category} is a valid Numbered Humor category

- keyed/types - returns a list of Keyed Humor Categories
- keyed/random/{category} - returns a random Keyed Humor record, where {category} is a valid Keyed Humor category
- keyed/specific/{category}/{which} - returns a specific Keyed Humor record, where {category} is a valid Keyed Humor category, and {which} is a specific Keyed Humor record id
- keyed/count/{category} - returns the count of Keyed Humor records, where {category} is a valid Keyed Humor category
- keyed/keys/{category} - returns the list of all the keys, where {category} is a valid Keyed Humor category

- dated/types - returns a list of Dated Humor Categories
- dated/random/{category} - returns a random Dated Humor record, where {category} is a valid Dated Humor category
- dated/specific/{category}/{month}/{day} - returns a specific Dated Humor record, where {category} is a valid Dated Humor category, and {month} is a specific Month (Zero based), and {day} is a specific Day
- dated/count/{category} - returns the count of Dated Humor records, where {category} is a valid Dated Humor category

The default response to any GET request is a JSON string.

The following two GET requests are syntactically identical:

- http://localhost:8080/HumorREST/api/numbered/random/fortunecookie
- http://localhost:8080/HumorREST/api/numbered/random/fortunecookie.json

Also available is an XML format:

- http://localhost:8080/HumorREST/api/numbered/random/fortunecookie.xml

In addition The HunorREST API support the following requests:

- POST: keyed/add the body of the POST request must contain a KeyedHumor object (in JSON or XML format)
- PUT: keyed/update the body of the PUT request must contain a KeyedHumor object (in JSON or XML format)
- DELETE: keyed/delete/{category}/{which} where {category} is a valid Keyed Humor category, and {which} is a specific Keyed Humor record id

### Category Definitions:

The Humor Categories include:

#### Numbered

- fortunes
- puns

#### Keyed

- buzzwords
- music
- mottos
- dictionary

#### Dated

- stickers

### Object Definitions:

The objects returned by GET requests include:

#### Categories

- An Array of Category objects

#### Category

- id
- type
- name
- description

#### NumberedList

- An Array of NumberedHumor objects

#### NumberedHumor

- type
- number
- message

#### KeyedList

- An Array of KeyedHumor objects

#### KeyedHumor

- type
- key
- message

#### Integer

- field
- value

#### DatedList

- An Array of DatedHumor objects

#### DatedHumor

- type
- month
- day
- message

#### Integer

- field
- value