Merge pull request #1939 from coreinfrastructure/openapi-spec

Create first draft of OpenAPI specification for website

best_practices.openapi.yaml

@@ -0,0 +1,183 @@
+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