FORMAT: 1A
HOST: https://paradigmagency.com/api/v1

# ParadigmCoreAPI


The Paradigm Core API is the central data hub of all Paradigm company data. It will be used by public resources (website) to get the data to display. It will be used by private resources to get and update data.

* ***THIS IS A WORK IN PROGRESS*** This documentation is in "alpha" version. Please leave comments by emailing `gavin@gavinr.com`
* ***Versioning*** This is version 1 of the api. Version (`/v1/` etc) is passed through the URI.
* ***Protocol*** API will *only* respond to requests over `https`
* ***Paging*** tbd
* ***Rate Limits*** tbd
* ***Timestamps*** will be in UTC time zone. Format will be `2012-01-01T12:00:00Z`.
* ***Status Codes*** We will support the following status codes:
  * **200**: Request succeeded for a GET, POST, DELETE, or PATCH call that completed synchronously,
  * **401 Unauthorized**: Request failed because user is not authenticated
  * **403 Forbidden**: Request failed because user does not have authorization to access a specific resource
  * **429 Too Many Requests**: You have been rate-limited (see above), retry later
  * **500 Internal Server Error**: Something went wrong on the server, check status site and/or report the issue
* ***Error Resonses*** will be a single object with three properties, like this:
  ```
  {
    "id":      "rate_limit",
    "message": "Account reached its API rate limit.",
    "url":     "https://docs.paradigmagency.com/rate-limits"
  }
  ```
* ***Social accounts*** give usernames or "public profile strings" that the clients of the API will use. (EX: for `"facebook": "whosaazar"`, take that string and append to `facebook.com` to get `https://facebook.com/whosaazar`)
* ***Language*** English only for now
* ***Filters*** We have attempted to provide all filters that you will need. If you need additional filters, please contact `gavin@gavinr.com`.
* ***Last updated*** Last updated 2016-10-23

`featured_rank` is used on multiple resources. It will always return an integer between 0 and 5. 0 being the lowest or "no ranking." 5 being the "highest ranking."

## Locations [/locations/{?sort,fields}]

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.

### List All Locations [GET]

Get a list of all the locations.

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "New York",
                "address1": "123 Main St.",
                "address2": "PO Box 30",
                "address3": "Mail Stop 3",
                "city": "New York City",
                "state": "NY",
                "postal": "12345",
                "postal_extended": "1112",
                "country_code": "USA",
                "x": -117.195667,
                "y": 34.056491000000001,
                "map_image_url": "https://paradigmagency.com/images/img1.png",
                "map_url": "https://www.google.com/maps/place/Paradigm/@40.7420557,-73.9874759,17z/data=!3m1!4b1!4m5!3m4!1s0x89c25908dd4de675:0x2f10fad017eced8a!8m2!3d40.7420557!4d-73.9852872",
                "telephone": "123-459-7994",
                "fax": "234-345-1234",
                "showHome": true,
                "region": {
                    "id": 1,
                    "name": "New York"
                }
            },
            {
                "id": 2,
                "name": "Beverly Hills",
                "address1": "123 Main St.",
                "address2": "PO Box 30",
                "address3": "Mail Stop 3",
                "city": "Beverly Hills",
                "state": "CA",
                "postal": "92031",
                "postal_extended": "1112",
                "country_code": "USA",
                "x": -117.195667,
                "y": 34.056491000000001,
                "map_image_url": "https://paradigmagency.com/images/img2.png",
                "map_url": "https://www.google.com/maps/place/Paradigm/@34.2790387,-118.7823295,10z/data=!4m8!1m2!2m1!1sparadigm+los+angeles!3m4!1s0x80c2bc0739180151:0x7dddb4819d369166!8m2!3d34.0714939!4d-118.3991847",
                "telephone": "123-459-7994",
                "fax": "234-345-1234",
                "showHome": false,
                "region": {
                    "id": 2,
                    "name": "Los Angeles"
                }
            }
        ]

## Location [/locations/{location_id}]
+ Parameters
    + location_id (number, required) - ID of the Location in the form of an integer

### View a Location Detail [GET]

Get a particular location, based on ID.

+ Response 200 (application/json)

        {
            "id": 1,
            "name": "New York",
            "address1": "123 Main St.",
            "address2": "PO Box 30",
            "address3": "Mail Stop 3",
            "city": "New York City",
            "state": "NY",
            "postal": "12345",
            "postal_extended": "1112",
            "country_code": "USA",
            "x": -117.195667,
            "y": 34.056491000000001,
            "map_image_url": "https://paradigmagency.com/images/img1.png",
            "map_url": "https://www.google.com/maps/place/Paradigm/@40.7420557,-73.9874759,17z/data=!3m1!4b1!4m5!3m4!1s0x89c25908dd4de675:0x2f10fad017eced8a!8m2!3d40.7420557!4d-73.9852872",
            "telephone": "123-459-7994",
            "fax": "234-345-1234",
            "showHome": true,
            "region": {
                "id": 1,
                "name": "New York"
            }
        }

## Artists [/artists/{?sort,fields,name,tribes,featuredrank}]

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.
    + name (string, optional) - filter based on `name` property (fuzzy search).
    + tribes (string, optional) - filter based on `tribes` id property. Comma-separated (logical OR)
    + featuredrank (number, optional) - filter based on featured_rank property.

### List All Artists [GET]

Get a list of all artists.

My convention, "media" field will be sorted from most promient to least, with the first image assumed to be the primary image.

+ Response 200 (application/json)

        [
            {
                "name": "Skrillex",
                "featured_rank": 4,
                "coda": false,
                "tribes": [
                    {
                        "id": 2,
                        "name":"Rock"
                    }, {
                        "id" :3,
                        "name":"Pop"
                    }
                ],
                "agents": [
                    "john_agent@paradigmagency.com",
                    "sally_agent@paradigmagency.com",
                    "robert_agent@paradigmagency.com"
                ],
                "url": "http://www.skrillex.com",
                "facebook": "skrillex",
                "instagram": "skrillex",
                "twitter": "skrillex",
                "vevo": "skrillex",
                "youtube": "skrillex",
                "snapchat": "skrillex",
                "spotify": "skrillex",
                "soundcloud": "skrillex",
                "bandsintown": "skrillex",
                "media": [{
                    "id": 1,
                    "url": "https://medialibrary.paradigmagency.com/skrillex.jpg",
                    "height": 500,
                    "width": 500
                }]
            },
            {
                "name": "ACES",
                "featured_rank": 0,
                "coda": false,
                "tribes": [
                    {
                        "id": 8,
                        "name":"Romance"
                    }, {
                        "id" :3,
                        "name":"Pop"
                    }
                ],
                "agents": [
                    "john_agent@paradigmagency.com",
                    "sally_agent@paradigmagency.com",
                    "robert_agent@paradigmagency.com"
                ],
                "url": "http://www.theseaces.com/",
                "facebook": "theseaces",
                "instagram": "theseaces",
                "twitter": "theseaces",
                "vevo": "theseaces",
                "youtube": "theseaces",
                "snapchat": "theseaces",
                "spotify": "theseaces",
                "soundcloud": "theseaces",
                "bandsintown": "theseaces",
                "media": [{
                    "id": 1,
                    "url": "https://medialibrary.paradigmagency.com/theseaces.jpg",
                    "height": 500,
                    "width": 500
                }]
            }
        ]

## Artist [/artists/{artist_id}]

+ Parameters
    + artist_id (number, required) - ID of the Artist in the form of an integer

### View an Artist Detail [GET]

Get a particular artist, based on ID

+ Response 200 (application/json)

        {
            "name": "Skrillex",
            "featured_rank": 4,
            "coda": false,
            "tribes": [
                {
                    "id": 2,
                    "name":"Rock"
                }, {
                    "id" :3,
                    "name":"Pop"
                }
            ],
            "agents": [
                "john_agent@paradigmagency.com",
                "sally_agent@paradigmagency.com",
                "robert_agent@paradigmagency.com"
            ],
            "url": "http://www.skrillex.com",
            "facebook": "skrillex",
            "instagram": "skrillex",
            "twitter": "skrillex",
            "vevo": "skrillex",
            "youtube": "skrillex",
            "snapchat": "skrillex",
            "spotify": "skrillex",
            "soundcloud": "skrillex",
            "bandsintown": "skrillex",
            "media": [{
                "id": 1,
                "url": "https://medialibrary.paradigmagency.com/skrillex.jpg",
                "height": 500,
                "width": 500
            }]
        }

## Pages [/pages/{?sort,fields}]

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.


### List All Pages [GET]

Get a list of all "pages" in the system. A "page" is a content block roughly associated with a page in the public website where we need to replicate a CMS-type functionality.

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "About",
                "slug": "publishing-about"
                "last_updated": "2016-01-01T09:59:40Z"
            },
            {
                "id": 2,
                "name": "Contact",
                "slug": "publishing-contact"
                "last_updated": "2015-01-01T14:00:00Z"
            }
        ]

## Page by ID [/pages/{page_id}]

+ Parameters
    + page_id (number, required) - ID of the Page in the form of an integer.

### Get page content [GET]

This will deliver back HTML, ideally for use by `jQuery.load` or equivalent.

+ Response 200 (text/html)

        <div>
            <div>At paradigm Publishing we believe that an artist who is successfull .....</div>
            <div>That's why we brainstorm with our colleagues in each division of the agency .....</div>
        </div>
        
## Page by slug [/pages/{page_slug}]

+ Parameters
    + page_slug (string, required) -  slug of the page in the form of a string. Current options include: [publishing-about, publishing-contact, contact]

### Get page content [GET]

This will deliver back HTML, ideally for use by `jQuery.load` or equivalent.

+ Response 200 (text/html)

        <div>
            <div>At paradigm Publishing we believe that an artist who is successfull .....</div>
            <div>That's why we brainstorm with our colleagues in each division of the agency .....</div>
        </div>

## Books [/books/{?sort,fields,name,author,bestseller,featuredrank}]

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.
    + name (string, optional) - filter based on `name` property (fuzzy search).
    + author (string, optional) - filter based on `author` property (fuzzy search).
    + bestseller (boolean, optional) - filter based on `bestseller` property.
    + featuredrank (number, optional) - filter based on featured_rank property.

### List Books [GET]

Get a list of all books.

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "Luckiest Girl Alive: A Novel",
                "description": "Lorem ipsum ...",
                "author": "Jessica Knoll",
                "url": "http://luckiestgirlalivebook.com",
                "released_date": "2015-08-05T08:40:51Z",
                "bestseller": true,
                "featured_rank": 5,
                "media": [{
                    "id": 4,
                    "url": "https://medialibrary.paradigmagency.com/LuckiestGirl.jpg",
                    "height": 500,
                    "width": 500
                }]
            },
            {
                "id": 2,
                "name": "I Was an Awesomer Kid",
                "description": "Face it: You were awesome when you were a kid. You feared nothing. You spoke your mind. You tried new things. You had imagination. Now you play by the rules, dress appropriately",
                "author": "Brad Getty",
                "url": "http://iwasanawesomerkid.tumblr.com/",
                "released_date": "2016-07-05T08:40:51Z",
                "bestseller": false,
                "featured_rank": 0,
                "media": [{
                    "id": 6,
                    "url": "https://medialibrary.paradigmagency.com/awesome.jpg",
                    "height": 400,
                    "width": 200
                }]
            }
        ]

## Book [/books/{book_id}]

+ Parameters
    + book_id (number, required) - ID of the Book in the form of an integer

### View a Book Detail [GET]

+ Response 200 (application/json)

        {
            "id": 1,
            "name": "Luckiest Girl Alive: A Novel",
            "description": "Lorem ipsum ...",
            "author": "Jessica Knoll",
            "url": "http://luckiestgirlalivebook.com",
            "released_date": "2015-08-05T08:40:51Z",
            "bestseller": true,
            "featured_rank": 5,
            "media": [{
                "id": 4,
                "url": "https://medialibrary.paradigmagency.com/LuckiestGirl.jpg",
                "height": 500,
                "width": 500
            }]
        }

## Jobs [/jobs/{?sort,fields,name,locationid}]

Get a list of all jobs. location_id is a foreign key out to the `/jobs/` endpoint objects.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.
    + name (string, optional) - filter based on `name` property (fuzzy search).
    + locationid (int, optional) - filter based on `location_id` property.

### List Jobs [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "Entry Level Position - Talent & Literary - NYC",
                "description": "Job description ...",
                "posted_on": "2015-08-05T08:40:51Z",
                "url": "http://myjobs.com?id=123",
                "location": {
                    "id": 1,
                    "name": "New York",
                    "address1": "123 Main St.",
                    "address2": "PO Box 30",
                    "address3": "Mail Stop 3",
                    "city": "New York City",
                    "state": "NY",
                    "postal": "12345",
                    "postal_extended": "1112",
                    "country_code": "USA",
                    "x": -117.195667,
                    "y": 34.056491000000001,
                    "map_image_url": "https://paradigmagency.com/images/img1.png",
                    "map_url": "https://www.google.com/maps/place/Paradigm/@40.7420557,-73.9874759,17z/data=!3m1!4b1!4m5!3m4!1s0x89c25908dd4de675:0x2f10fad017eced8a!8m2!3d40.7420557!4d-73.9852872",
                    "telephone": "123-459-7994",
                    "fax": "234-345-1234",
                    "showHome": true,
                    "region": {
                        "id": 1,
                        "name": "New York"
                    }
                }
            },
            {
                "id": 2,
                "name": "Agent - Music - Beverly Hills",
                "description": "Job description ...",
                "posted_on": "2015-08-18T08:40:51Z",
                "url": "http://myjobs.com?id=234",
                "location": {
                    "id": 2,
                    "name": "Beverly Hills",
                    "address1": "123 Main St.",
                    "address2": "PO Box 30",
                    "address3": "Mail Stop 3",
                    "city": "Beverly Hills",
                    "state": "CA",
                    "postal": "92031",
                    "postal_extended": "1112",
                    "country_code": "USA",
                    "x": -117.195667,
                    "y": 34.056491000000001,
                    "map_image_url": "https://paradigmagency.com/images/img2.png",
                    "map_url": "https://www.google.com/maps/place/Paradigm/@34.2790387,-118.7823295,10z/data=!4m8!1m2!2m1!1sparadigm+los+angeles!3m4!1s0x80c2bc0739180151:0x7dddb4819d369166!8m2!3d34.0714939!4d-118.3991847",
                    "telephone": "123-459-7994",
                    "fax": "234-345-1234",
                    "showHome": false,
                    "region": {
                        "id": 2,
                        "name": "Los Angeles"
                    }
                }
            }
            
        ]

## Job [/jobs/{job_id}]

Get a particular job

+ Parameters
    + job_id (number, required) - ID of a job

### View a Job Detail [GET]

+ Response 200 (application/json)

        {
            "id": 1,
            "name": "Entry Level Position - Talent & Literary - Beverly Hills",
            "description": "Job description ...",
            "location_id": 2,
            "posted_on": "2015-08-05T08:40:51.620Z"
        }
        
## Voiceover Artists [/voiceover-artists/{?sort,fields,name,featuredrank,gender,categories,descriptors,ages,languages}]

Get a list of all voiceover artists.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + fields (string, optional) - comma-separated list of fields to include in the response. If not included, or `?fields=` implies return everything.
    + name (string, optional) - filter based on `name` property (fuzzy search).
    + featuredrank (number, optional) - filter based on featured_rank property.
    + gender (string, optional) - filter based on `gender` property (fuzzy search).
    + categories (string, optional) - filter based on `categories` id property. Comma-separated (logical OR)
    + descriptors (string, optional) - filter based on `descriptors` id property. Comma-separated (logical OR)
    + ages (string, optional) - filter based on `ages` id property. Comma-separated (logical OR)
    + languages (string, optional) - filter based on `languages` id property. Comma-separated (logical OR)

### List Voiceover Artists [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "first_name": "Jason",
                "last_name": "Alexander",
                "biography": "Josh Alexander is a ....",
                "featured_rank": 1,
                "gender":"male",
                "audio_clip_media": {
                    "id": 1,
                    "url": "https://medialibrary.paradigmagency.com/joshAlexander.mp3",
                    "height": null,
                    "width": null
                },
                "categories":[{
                    "id": 1,
                    "name": "Promo"
                }, {
                    "id": 4,
                    "name": "Political"
                }],
                "descriptors": [{
                    "id": 1,
                    "name":"Gritty"
                }, {
                    "id": 3,
                    "name": "Attractive"
                }],
                "ages": [{
                    "id": 2,
                    "name": "Teen"
                }],
                "languages": [{
                    "id": 1,
                    "name": "English"
                }]
            }
        ]

## Voiceover Artist [/voiceover-artists/{artist_id}]

Get a single voiceover artist.

+ Parameters
    + artist_id (number, required) - ID of the Voiceover Artist in the form of an integer

### Get Voiceover Artist [GET]

+ Response 200 (application/json)

        {
            "id": 1,
            "first_name": "Jason",
            "last_name": "Alexander",
            "biography": "Josh Alexander is a ....",
            "featured_rank": 1,
            "gender":"male",
            "audio_clip_media": {
                "id": 1,
                "url": "https://medialibrary.paradigmagency.com/joshAlexander.mp3",
                "height": null,
                "width": null
            },
            "categories":[{
                "id": 1,
                "name": "Promo"
            }, {
                "id": 4,
                "name": "Political"
            }],
            "descriptors": [{
                "id": 1,
                "name":"Gritty"
            }, {
                "id": 3,
                "name": "Attractive"
            }],
            "ages": [{
                "id": 2,
                "name": "Teen"
            }],
            "languages": [{
                "id": 1,
                "name": "English"
            }]
        }

        
## Categories [/categories/{?sort,name}]

Get a list of all voiceover artist categories.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + name (string, optional) - filter based on `name` property (fuzzy search).

### List Categories [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "Promo"
            },
            {
                "id": 2,
                "name": "Commercial / Industrial"
            },
            {
                "id": 3,
                "name": "Narration / Documentary"
            }
        ]

## Descriptors [/descriptors/{?sort,name}]

Get a list of all voiceover artist descriptors.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + name (string, optional) - filter based on `name` property (fuzzy search).

### List Descriptors [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "Gritty"
            },
            {
                "id": 2,
                "name": "Aggressive"
            },
            {
                "id": 3,
                "name": "Attractive"
            }
        ]

## Ages [/ages/{?sort,name}]

Get a list of all voiceover artist ages.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + name (string, optional) - filter based on `name` property (fuzzy search).

### List Ages [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "Child"
            },
            {
                "id": 2,
                "name": "Teen"
            },
            {
                "id": 3,
                "name": "Young Adult"
            }
        ]

## Languages [/languages/{?sort,name}]

Get a list of all voiceover artist languages.

+ Parameters
    + sort (string, optional) - comma-separated list of fields. Each field can be prepended with a "-" to imply descending sort order. EXAMPLE: `/locations?sort=state` or `/locations?sort=state,-country_code`
    + name (string, optional) - filter based on `name` property (fuzzy search).

### List Languages [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "English"
            },
            {
                "id": 2,
                "name": "Spanish"
            },
            {
                "id": 3,
                "name": "Greek"
            }
        ]
        
## Landing-Page Voiceover Artists [/voiceover-artists/landing]

Get a list of all voiceover artists that should be on the landing page. Each record will have an "order", a reference to the media item (picture) to show, and a reference to an artist.

### List Landing-page Voiceover Artists [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "display_order": 1,
                "voiceover_artist": {
                    "id": 1,
                    "name": "Josh Alexander",
                    "biography": "Josh Alexander is a ....",
                    "featured_rank": 1,
                    "gender":"male",
                    "audio_clip_media": {
                        "id": 1,
                        "url": "https://medialibrary.paradigmagency.com/joshAlexander.mp3",
                        "height": null,
                        "width": null
                    },
                    "categories":[{
                        "id": 1,
                        "name": "Promo"
                    }, {
                        "id": 4,
                        "name": "Political"
                    }],
                    "descriptors": [{
                        "id": 1,
                        "name":"Gritty"
                    }, {
                        "id": 3,
                        "name": "Attractive"
                    }],
                    "ages": [{
                        "id": 2,
                        "name": "Teen"
                    }],
                    "languages": [{
                        "id": 1,
                        "name": "English"
                    }]
                },
                "media": {
                    "id": 1,
                    "url": "https://medialibrary.paradigmagency.com/joshAlexander.jpg",
                    "height": 500,
                    "width": 400
                }
            }
        ]