swagger: "2.0"
schemes:
  - https
  - http
host: api.jokes.one
info:
  contact:
    name: Jokes One
    url: https://jokes.one/api/joke/
  description: " Jokes One API offers a complete feature rich REST API access to its jokes platform.  This is the documentation for the world famous [jokes API](https://jokes.one/api/joke/).  If you are a subscriber and you are trying this from a console add 'X-JokesOne-Api-Secret' header and add your api key as the header value. You can test and play with the API right here on this web page. For using the private end points and subscribing to the API please visit https://jokes.one/api/joke/."
  termsOfService: https://jokes.one/terms
  title: Jokes One API
  version: "1.1"
  x-apisguru-categories:
    - entertainment
  x-issues:
    - https://github.com/APIs-guru/openapi-directory/issues/743
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://jokes.one/branding/smile_magenta.png
  x-origin:
    - format: swagger
      url: https://api.jokes.one/yaml/jokes.one.yaml
      version: "2.0"
  x-providerName: jokes.one
  x-tags:
    - helpWanted
consumes:
  - application/json
produces:
  - application/json
  - application/xml
  - application/js
securityDefinitions:
  X-JokesOne-Api-Secret:
    in: header
    name: X-JokesOne-Api-Secret
    type: apiKey
tags:
  - description: "Access joke of the day service. Use this to get the joke of the day in various categories. This is a free API that is available to public. You must credit Jokes One if you are using the free version. "
    externalDocs:
      description: Find out more
      url: https://jokes.one/api#joke-of-the-day
    name: jod
  - description: Access random joke service. Use this to get random jokes , jokes filtered by authors or tags etc. You need an API key to access this service.
    name: joke
paths:
  /jod:
    get:
      description: |
        Gets `Joke of the Day`.
        Optional `category` param determines
        the category of returned joke of the day
      parameters:
        - description: JOD Category
          format: string
          in: query
          name: category
          required: false
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                "total": 1
                  },
                  "contents": {
                "jokes": [
                    {
                  "category": "animal",
                  "title": "Animal Joke of the day ",
                  "description": "Animal Joke of the day ",
                  "background": "",
                  "joke": {
                      "title": "Elephant with Diarrhea",
                      "length": "67",
                      "clean": "0",
                      "racial": "0",
                      "date": "2018-11-05",
                      "id": "1tO_XKcm3_qYMkk0k19HEgeF",
                      "text": "What do you give an elephant with diarrhea? \r\n\r\n\r\nLots of room.\r\n\r\n"
                  }
                    }
                ],
                "copyright": "2018-20 https://jokes.one"
                  }
              }
            application/xml: |-
              <?xml version="1.0"?>
              <response>
                <success>
                  <total>1</total>
                </success>
                <contents>
                  <jokes>
                    <category>animal</category>
                    <title>Animal Joke of the day </title>
                    <description>Animal Joke of the day </description>
                    <background/>
                    <joke>
                      <title>Elephant with Diarrhea</title>
                      <length>67</length>
                      <clean>0</clean>
                      <racial>0</racial>
                      <date>2018-11-05</date>
                      <id>1tO_XKcm3_qYMkk0k19HEgeF</id>
                      <text>What do you give an elephant with diarrhea? &#xD; &#xD; &#xD; Lots of room.&#xD; &#xD;</text>
                    </joke>
                  </jokes>
                  <copyright>2018-20 https://jokes.one</copyright>
                </contents>
              </response>
          schema:
            $ref: "#/definitions/JokeOfTheDayResponse"
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - jod
  /jod/categories:
    get:
      description: |
        Gets a list of `Joke of the Day` Categories.
      produces:
        - application/xml
        - application/json
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                "total": 3
                  },
                  "contents": {
                "categories": {
                    "jod": {
                  "category": "jod",
                  "title": "Joke of the day ",
                  "description": "Joke of the day ",
                  "background": ""
                    },
                    "animal": {
                  "category": "animal",
                  "title": "Animal Joke of the day ",
                  "description": "Animal Joke of the day ",
                  "background": ""
                    },
                    "blonde": {
                  "category": "blonde",
                  "title": "Blonde joke of the day!",
                  "description": "Blonde joke of the day!",
                  "background": ""
                    }
                },
                "copyright": "2018-20 https://jokes.one"
                  }
              }
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - jod
  /joke:
    delete:
      description: |
        Delete a joke. The user needs to be the owner of the joke to be able to delete it.
      parameters:
        - description: Joke ID
          format: string
          in: query
          name: id
          required: true
          type: string
      produces:
        - application/json
        - application/xml
      responses:
        "200":
          description: 200  response
          examples:
            application/xml: "{}"
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
        "404":
          description: 404  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 404,
                      "message": "Not Found: Joke not found"
                  }
              }                      
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - joke
    get:
      description: Gets a `Joke` with a given `id`.
      parameters:
        - description: Joke ID
          format: string
          in: query
          name: id
          required: false
          type: string
      produces:
        - application/json
        - application/xml
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                      "total": 1
                  },
                  "contents": {
                      "jokes": [
                          {
                              "title": "Anti aircraft weapon",
                              "length": "212",
                              "clean": null,
                              "racial": null,
                              "id": "pZdOqARLsLVZ84EkBcWptAeF",
                              "text": "\nThe USA blamed the Russian companies that they were supplying Bagdad with the elastic band for pants. Iraq engineers made the catapults of them and now Iraq soldiers are striking a blow to American air forces.\n\n"
                          }
                      ],
                      "copyright": "2018-20 https://jokes.one"
                  }
              }
            application/xml: |-
              <?xml version="1.0"?>
              <response>
                <success>
                  <total>1</total>
                </success>
                <contents>
                  <jokes>
                    <title>Anti aircraft weapon</title>
                    <length>212</length>
                    <clean/>
                    <racial/>
                    <id>pZdOqARLsLVZ84EkBcWptAeF</id>
                    <text>
              The USA blamed the Russian companies that they were supplying Bagdad with the elastic band for pants. Iraq engineers made the catapults of them and now Iraq soldiers are striking a blow to American air forces.

              </text>
                  </jokes>
                  <copyright>2018-20 https://jokes.one</copyright>
                </contents>
              </response>
          schema:
            $ref: "#/definitions/JokeResponse"
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - joke
    patch:
      description: Update a joke
      parameters:
        - description: Joke ID
          format: string
          in: query
          name: id
          required: true
          type: string
        - description: title
          format: string
          in: query
          name: title
          required: false
          type: string
        - description: text
          format: string
          in: query
          name: text
          required: false
          type: string
        - description: Joke Author
          format: string
          in: query
          name: author
          required: false
          type: string
        - description: Comma Separated tags
          in: query
          name: tags
          required: false
          type: string
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                "success": {
                  "total": 1
                },
                "content": {
                  "joke": {
                    "id": "0tztT1wYHRzdTf7jIccAzweF"
                  }
                }
              }
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }              
      tags:
        - joke
    put:
      description: Add a new joke to your private collection.
      parameters:
        - description: Joke Title
          format: string
          in: query
          name: title
          required: true
          type: string
        - description: Joke Text
          format: string
          in: query
          name: text
          required: true
          type: string
        - description: Joke Author
          format: string
          in: query
          name: author
          required: false
          type: string
        - description: Comma Separated tags
          format: string
          in: query
          name: tags
          required: false
          type: string
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                "success": {
                  "total": 1
                },
                "content": {
                  "joke": {
                    "id": "0tztT1wYHRzdTf7jIccAzweF"
                  }
                }
              }
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }              
      tags:
        - joke
  /joke/categories/search:
    get:
      description: |
        Gets a list of `Joke` Categories, based on a query term.
      parameters:
        - description: Search Query
          format: string
          in: query
          name: query
          required: true
          type: string
        - default: 0
          description: Response is paged. This parameter controls where response starts the listing at
          format: int32
          in: query
          name: start
          required: false
          type: integer
      produces:
        - application/xml
        - application/json
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                      "total": 8
                  },
                  "contents": {
                      "categories": {
                          "jod": "Joke of the day",
                          "work": "Work Related Joke of the day",
                          "kids": "Joke of the day for kids"
                      },
                      "copyright": "2018-20 https://jokes.one"
                  }
              }    
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - joke
  /joke/list:
    get:
      description: Get the list of jokes in your private collection.
      parameters:
        - default: 0
          description: Response is paged. This parameter controls where response starts the listing at
          format: int32
          in: query
          name: start
          required: false
          type: integer
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                      "total": "263",
                      "range": {
                          "start": 0,
                          "end": 5
                      }
                  },
                  "contents": {
                      "jokes": [
                          {
                              "joke": "I think you should defend to the death their right to march, and then go down and meet them with baseball bats.",
                              "length": "111",
                              "author": "Woody Allen",
                              "tags": [],
                              "id": "GkeLUydBfiAH0Tcs2w_gwAeF"
                          },
                          {
                              "joke": "We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altogether fitting and proper that we should do this. ... The world will little note nor long remember what we say here, but it can never forget what they did here.",
                              "length": "310",
                              "author": "Abraham Lincoln",
                              "tags": [],
                              "id": "u6fD9eRFA2NFMHuEoeujaAeF"
                          },
                          {
                              "joke": "Eighty percent of success is showing up.",
                              "length": "40",
                              "author": "Woody Allen",
                              "tags": [
                                  "success",
                                  "tso-top-100"
                              ],
                              "id": "nLvp0vLfofW06PILxmERHgeF"
                          },
                          {
                              "joke": "Great ambition is the passion of a great character.  Those endowed with it may perform very good or very bad acts.  All depends on the principals which direct them.",
                              "length": "164",
                              "author": "Napoleon Bonaparte",
                              "tags": [
                                  "ambition",
                                  "inspire",
                                  "passion"
                              ],
                              "id": "X8juAoTtvxSEdgA0sGbYeQeF"
                          },
                          {
                              "joke": "I have had dreams, and I have had nightmares. I overcame the nightmares because of my dreams.",
                              "length": "93",
                              "author": "Dr. Jonas Salk",
                              "tags": [
                                  "dream",
                                  "nightmare"
                              ],
                              "id": "m_6Fj8QcXlVsQiiW7SAMLAeF"
                          }
                      ]
                  }
              }
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              } 
      tags:
        - joke
  /joke/random:
    get:
      description: Gets a `Random Joke`. When you are in a hurry this is what you call to get a random famous joke.
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                      "total": 1
                  },
                  "contents": {
                      "jokes": [
                          {
                              "title": "Blonde tap dancer",
                              "length": "86",
                              "clean": "0",
                              "racial": "0",
                              "id": "SVEPCMsk3SbyeWZbERGzKQeF",
                              "text": "What happened to the blonde tap dancer? \r\nShe slipped off and fell down the drain.\r\n\r\n"
                          }
                      ],
                      "copyright": "2018-20 https://jokes.one"
                  }
              }
            application/xml: |-
              <?xml version="1.0"?>
              <response>
                <success>
                  <total>1</total>
                </success>
                <contents>
                  <jokes>
                    <title>Blonde tap dancer</title>
                    <length>86</length>
                    <clean>0</clean>
                    <racial>0</racial>
                    <id>SVEPCMsk3SbyeWZbERGzKQeF</id>
                    <text>What happened to the blonde tap dancer? &#xD;
              She slipped off and fell down the drain.&#xD;
              &#xD;
              </text>
                  </jokes>
                  <copyright>2018-20 https://jokes.one</copyright>
                </contents>
              </response>
          schema:
            $ref: "#/definitions/JokeResponse"
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
      tags:
        - joke
  /joke/search:
    get:
      description: "Search for a `Joke` in Jokes One platform. Optional `category` , `author`, `minlength`, `maxlength` params determines the filters applied while searching for the joke. "
      parameters:
        - description: Joke Category
          format: string
          in: query
          name: category
          required: false
          type: string
        - description: keyword to search for in the joke
          format: string
          in: query
          name: query
          required: false
          type: string
        - default: 100
          description: Joke minimum Length
          format: int32
          in: query
          name: minlength
          required: false
          type: integer
        - default: 300
          description: Joke maximum Length
          format: int32
          in: query
          name: maxlength
          required: false
          type: integer
        - description: Joke Author
          format: string
          in: query
          name: author
          required: false
          type: string
        - default: false
          description: Should search private collection? Default searches public collection.
          format: boolean
          in: query
          name: private
          required: false
          type: boolean
      produces:
        - application/json
        - application/xml
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
                  "success": {
                      "total": 1
                  },
                  "contents": {
                      "jokes": [
                          {
                              "title": "Blonde tap dancer",
                              "length": "86",
                              "clean": "0",
                              "racial": "0",
                              "id": "SVEPCMsk3SbyeWZbERGzKQeF",
                              "text": "What happened to the blonde tap dancer? \r\nShe slipped off and fell down the drain.\r\n\r\n"
                          }
                      ],
                      "copyright": "2018-20 https://jokes.one"
                  }
              }
            application/xml: |-
              <?xml version="1.0"?>
              <response>
                <success>
                  <total>1</total>
                </success>
                <contents>
                  <jokes>
                    <title>Blonde tap dancer</title>
                    <length>86</length>
                    <clean>0</clean>
                    <racial>0</racial>
                    <id>SVEPCMsk3SbyeWZbERGzKQeF</id>
                    <text>What happened to the blonde tap dancer? &#xD;
              She slipped off and fell down the drain.&#xD;
              &#xD;
              </text>
                  </jokes>
                  <copyright>2018-20 https://jokes.one</copyright>
                </contents>
              </response>        
          schema:
            $ref: "#/definitions/JokeResponse"
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
      security:
        - X-JokesOne-Api-Secret: []
      tags:
        - joke
  /joke/tags/add:
    post:
      description: Add a tag to a given Joke.
      parameters:
        - description: Joke ID
          format: string
          in: query
          name: id
          required: true
          type: string
        - description: Comma Separated tags
          format: string
          in: query
          name: tags
          required: true
          type: string
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
              }
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
        "404":
          description: 404  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 404,
                      "message": "Not Found: Joke not found"
                  }
              }                      
      tags:
        - joke
  /joke/tags/remove:
    post:
      description: Remove a tag from a given joke.
      parameters:
        - description: Joke ID
          format: string
          in: query
          name: id
          required: true
          type: string
        - description: Comma Separated tags
          format: string
          in: query
          name: tags
          required: true
          type: string
      responses:
        "200":
          description: 200  response
          examples:
            application/json: |-
              {
              }
        "401":
          description: 401  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 401,
                      "message": "Unauthorized"
                  }
              }
        "404":
          description: 404  response
          examples:
            application/json: |-
              {
                  "error": {
                      "code": 404,
                      "message": "Not Found: Joke not found"
                  }
              }                      
      tags:
        - joke
definitions:
  Joke:
    allOf:
      - $ref: "#/definitions/NewJoke"
      - properties:
          id:
            description: Unique identifier representing a specific joke in jokes.one.
            type: string
          image:
            description: Image URL that can be used for background to display this joke.
            type: string
          length:
            description: Length of the joke string.
            format: int32
            type: integer
        type: object
  JokeOfTheDay:
    allOf:
      - $ref: "#/definitions/Joke"
      - properties:
          date:
            description: Date this joke of the day belongs to
            type: string
        required:
          - date
  JokeOfTheDayResponse:
    properties:
      contents:
        properties:
          jokes:
            description: List of jokes
            items:
              $ref: "#/definitions/JokeOfTheDay"
            type: array
      success:
        description: Metadata about this successful call
        type: string
  JokeResponse:
    properties:
      contents:
        properties:
          jokes:
            description: List of jokes
            items:
              $ref: "#/definitions/Joke"
            type: array
      success:
        description: Metadata about this successful call
        type: string
  NewJoke:
    properties:
      author:
        description: Author name of joke.
        type: string
      joke:
        description: The Joke.
        type: string
      tags:
        description: Array of tags/categories.
        items:
          type: string
        type: array
      title:
        description: Title of the Joke.
        type: string
    required:
      - joke
      - title
