As a developer I want to design the best possible API so I can implement it in a stable future-proof manner

[abompard]

Things to think about when designing the API:

• REST and HTTP links between results
• API version
• schema (food for thought: OpenAPI, CoreAPI, Swagger, etc)
• handling of paginated results
• writing a client should be easy

Acceptance criteria:

• The schema format has been decided
• We have a good vision of how fasjson's API should look like

DoD: all of the above

[odra]

I would lean towards giving OpenAPI a try because:

• It has client generators: https://github.com/OpenAPITools/openapi-generator
• Pagination can be achieved by using links, such as: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L28
• Swagger tooling supports it

[odra]

I am writing a simple example using the openapi spec

[odra]

I'v' created a simple openapi sample:

openapi: 3.0.0
info:
  title: Fedora Account Service JSON API
  version: 0.0.1
paths:
  /1/:
    get:
      operationId: whoami
      responses:
        "401":
          description: requester identity authentication error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "200":
          description: requester identity success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/user"
          links:
            user:
              $ref: "#/components/links/UserProfile"
  /1/groups:
    get:
      operationId: queryGroups
      parameters:
        - name: query
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
      responses:
        "404":
          description: no groups for this user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        "200":
          description: get user groups
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/groups"
          links:
            pagination:
              $ref: "#/components/links/GroupPaging"
components:
  schemas:
    user:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
    group:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        total_users:
          type: integer
    groups:
      type: array
      items:
        $ref: "#/components/schemas/group"
    group_page:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/groups"
        pagination:
          type: object
          properties:
            current:
              type: integer
            previous:
              type: integer
            next:
              type: integer
    error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          type: object
  links:
    UserProfile:
      operationId: whoami
      parameters:
        id: $response.body#/id
    GroupPaging:
      operationId: queryGroups
      parameters:
        previous:
          operationId: queryGroups
          page: $response.body#/pagination/previous
          per_page: $request.query.per_page
          query: $request.query.query
        current:
          operationId: queryGroups
          page: $response.body#/pagination/current
          per_page: $request.query.per_page
          query: $request.query.query
        next:
          operationId: queryGroups
          page: $response.body#/pagination/next
          per_page: $request.query.per_page
          query: $request.query.query

The code can be used in swagger: https://editor.swagger.io/

I used the jsonprc spec for the error schema: https://www.jsonrpc.org/specification

I did not add it into the spec but a HEAD request into each path could return its own schema and a HEAD request to / would return the whole spec (either in json or yaml)

[StephenCoady]

This looks good. I don't have much experience with formal api spec - so the following might be dumb questions/statements:

• We should probably mention the licence.
• Do we need to mention auth at the top level? Do we know what that will look like wrt kerberos? It looks like negotiate was at least implemented: Support for Kerberos and others as type values of Security Scheme Object OAI/OpenAPI-Specification#451
• I'm not sure the /groups is specific to a user, but I could be wrong
• I think we also need /user/{user} and /group/{group} paths
• Does each path need to handle a 401 seperately or do they inherit from /?

[odra]

• The license is GPLv3, the same as this repository.
• yes we do, I didn't add it since I didn't find anything in the spec reference
• If I got that right from the code, it queries groups using your token, so it will return whatever groups you have access/read permission
• I only added methods that are already in the app code (whoami, groups and users)
• I set error responses and the "default" ones for each method in the PR, we can add specific ones later if needed
• The spec in hardcoded as a yaml file for now but it can be auto generated in the future

[StephenCoady]

I didn't see the PR, I thought you just wanted feedback on the comment 🤦‍♂️