best_practices.openapi.yaml

openapi: 3.0.0
info:
  title: Best Practices API
  description: RESTful API for OpenSSF Best Practices badge website
  version: 1.0.0
servers:
  - url: https://bestpractices.coreinfrastructure.org
    description: Main site
paths:
  /{locale}/projects/{id}/{level}.{format}:
    get:
      summary: Retrieve project data
      description: Returns data for project :id in :format. An empty format suffix returns HTML, and the ".json" format suffix returns JSON. External interfaces should normally request format "json". If "level" is given (0, 1, or 2), that level is shown (level is ignored if json format is requested, because we just provide all the data when JSON is requested).
      parameters:
        - name: locale
          in: path
          description: The locale for the requested data
          required: false
          schema:
            type: string
            default: en
        - name: id
          in: path
          description: The ID of the project to retrieve
          required: true
          type: string
        - name: level
          in: path
          description: The badge level of data to retrieve (0, 1, or 2); the level is ignored if json is requested. Level 0 is passing, 1 is silver, 2 is gold.
          required: false
          type: integer
        - name: format
          in: path
          description: The format of the returned data (json, html, or omitted for html)
          required: false
          type: string
          enum:
            - json
            - html
      responses:
        '200':
          description: Project data retrieved successfully
        '404':
          description: Project not found
        '500':
          description: Internal server error
  /{locale}/projects/{id}/badge.{format}:
    get:
      summary: Retrieve badge display
      description: Returns badge display for project :id in :format. An empty format suffix returns SVG, and the ".json" format suffix returns JSON. If you just want to the badge status of a project, retrieve this as JSON and look at the key badge_level.
      parameters:
        - name: locale
          in: path
          description: The locale for the requested data
          required: false
          schema:
            type: string
            default: en
        - name: id
          in: path
          description: The ID of the project to retrieve
          required: true
          type: string
        - name: format
          in: path
          description: The format of the returned badge display (json or svg)
          required: false
          type: string
          enum:
            - json
            - svg
      responses:
        '200':
          description: Badge display retrieved successfully
        '404':
          description: Project not found
        '500':
          description: Internal server error
  /{locale}/projects{format}:
    get:
      summary: Get a list of projects
      parameters:
        - name: locale
          in: path
          required: false
          description: The locale to use for the project names and descriptions
          schema:
            type: string
            default: en
        - name: format
          in: path
          required: false
          description: The format to return the response in (html, json, csv)
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter projects by status
          schema:
            type: string
            enum:
              - passing
              - in_progress
              - silver
              - gold
        - name: gteq
          in: query
          required: false
          description: Filter projects with a passing rate greater than or equal to the specified percentage
          schema:
            type: integer
        - name: lteq
          in: query
          required: false
          description: Filter projects with a passing rate less than or equal to the specified percentage
          schema:
            type: integer
        - name: url
          in: query
          required: false
          description: Filter projects by the home or repo URL
          schema:
            type: string
        - name: pq
          in: query
          required: false
          description: Filter projects by a prefix query against the URL or name
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Filter projects by a normal query against the parsed name, description, or URL
          schema:
            type: string
        - in: query
          name: as
          description: Display format for the resulting project badge that matches this query. The query must match exactly *one* project. Note that using this is rate-limited; "as=badge" is great for quick work, but not for mass use.
          required: true
          schema:
            type: string
          example: badge
        - name: page
          in: query
          required: false
          description: The page number to return. The first page is page 1.
          schema:
            type: integer
      responses:
        '200':
          description: A list of projects
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
            text/csv:
              schema:
                type: string
        '404':
          description: No matching project found
      tags:
        - Projects
components:
  schemas:
    Project:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        url:
          type: string
        passing_rate:
          type: number
        status:
          type: string