openapi: 3.0.3
info:
  title: 'ElePHPant.me API'
  description: 'A free, public JSON API for the PHP community.'
  version: 1.0.0
  license:
    name: MIT
    url: 'https://github.com/jgrossi/elephpant.me/blob/master/LICENSE'
servers:
  - url: 'https://elephpant.me'
tags:
  - name: Countries
    description: 'Which countries have public collectors, and how many.'
  - name: Elephpants
    description: 'The elePHPant species catalogue and per-species ownership stats.'
  - name: Herds
    description: "A single collector's herd of elePHPants."
  - name: Ranking
    description: 'Collector leaderboards, globally or scoped to a country.'
paths:
  /api/countries:
    get:
      summary: 'List countries with public collectors'
      operationId: listCountriesWithPublicCollectors
      description: "Returns every country that has at least one public herd, with its alpha-3 code, name\nand collector count, ordered by collector count descending then name ascending. Use\nthis to discover which country codes are worth passing to /ranking or\n/herd/{username} lookups, instead of scraping the ranking page's country selector."
      parameters: []
      responses:
        503:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Service Unavailable'
                properties:
                  message:
                    type: string
                    example: 'Service Unavailable'
      tags:
        - Countries
      security: []
  /api/elephpants:
    get:
      summary: 'List all elephpants'
      operationId: listAllElephpants
      description: 'Returns a paginated list of all elephpant species, ordered by year and name.'
      parameters:
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        503:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Service Unavailable'
                properties:
                  message:
                    type: string
                    example: 'Service Unavailable'
      tags:
        - Elephpants
      security: []
  '/api/elephpants/{id}':
    get:
      summary: 'Get a single elePHPant'
      operationId: getASingleElePHPant
      description: ''
      parameters: []
      responses:
        503:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Service Unavailable'
                properties:
                  message:
                    type: string
                    example: 'Service Unavailable'
      tags:
        - Elephpants
      security: []
    parameters:
      -
        in: path
        name: id
        description: 'elePHPant ID.'
        example: 1
        required: true
        schema:
          type: integer
  '/api/herd/{username}':
    get:
      summary: "Get a collector's herd"
      operationId: getACollectorsHerd
      description: 'Returns the full herd of a registered collector, including statistics and collected elePHPants. 403s if the herd is private.'
      parameters: []
      responses:
        503:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Service Unavailable'
                properties:
                  message:
                    type: string
                    example: 'Service Unavailable'
      tags:
        - Herds
      security: []
    parameters:
      -
        in: path
        name: username
        description: 'Collector username.'
        example: john
        required: true
        schema:
          type: string
  /api/ranking:
    get:
      summary: 'List the top collectors'
      operationId: listTheTopCollectors
      description: "Returns public herds ranked by number of unique elePHPants, then by total elePHPants,\nthen alphabetically by name. `rank` is the position in the full ordering (not\npage-relative), and `updated_at` is an exact timestamp, not a rendered relative\nstring, so it stays accurate however long you hold onto the response."
      parameters:
        -
          in: query
          name: country
          description: 'ISO 3166-1 alpha-3 country code to filter the ranking by.'
          example: GBR
          required: false
          schema:
            type: string
            description: 'ISO 3166-1 alpha-3 country code to filter the ranking by.'
            example: GBR
        -
          in: query
          name: page
          description: 'Page number.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number.'
            example: 1
      responses:
        503:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Service Unavailable'
                properties:
                  message:
                    type: string
                    example: 'Service Unavailable'
      tags:
        - Ranking
      security: []