Proposal endpoint changes

[maartenvn]

I would propose following changes that would allow the frontend for easier and cleaner development.

Endpoint changes

Projects

• GET /projects

  • Get a list with available projects
  • takes: nothing
  • returns: { id, name, description, repositories(link to repositories for project) }

• POST /projects

  • Create a new project
  • takes: project create variables
  • returns: the new project

• GET /projects/:id

  • Get a project by id.
  • takes: nothing
  • returns: { id, name, description, repositories(link to repositories for project) }

• DELETE /projects/:id

  • Delete a project by id.
  • takes: nothing
  • returns: nothing

• PATCH /projects/:id

  • Patch a project by id.
  • takes: only variables to change
  • returns: nothing

• GET /projects/:id/repositories

  • Get a list of repositories for the given project id.
  • takes: nothing
  • returns: repositories

• GET /projects/:id/issues

  • Get a list of issues for the given project id.
  • takes: nothing
  • returns: issues

• GET /projects/:id/pullrequests

  • Get a list of pull requests for the given project id.
  • takes: nothing
  • returns: pull requests

Repositories

• GET /repositories

  • Get a list with available repositories
  • takes: nothing
  • returns: repositories

• GET /repositories/:id

  • Get a repository by id.
  • takes: nothing
  • returns: repository

• POST /repositories/:id/link/:projectId

  • Link a repository to a project
  • takes: nothing
  • returns: nothing

• POST /repositories/:id/unlink/:projectId

  • Unlink a repository from a project.
  • takes: nothing
  • returns: nothing

• POST /repositories/sync

  • Sync the repositories with Github.
  • takes: nothing
  • returns: nothing

In essence

• I would suggest using plural names for every endpoint that supports collections.
• When an endpoint returns a collection, return the collection as root, without any key (eg /repositories does not return "repo": [], but rather []
• Rename name_id -> id for every endpoint.
• Use camelCase for every property name.
• Change all update endpoints to a PATCH, where you only have to send the fields that have to change.
• Add hyperlinked data instead of an array of ids (this means adding a separate endpoint)
  • eg: repos: [10, 11] -> repositories: "https://url/projects/2/repositories"
  • so not a list of links, that would make things harder in the frontend
  • this also saves a lot on request times, certainly when a lot of repositories will be linked (HTTP2 is a thing but a lot of requests will take quit a significant time)

Error handling

When an error occurs, it should be displayed in a proper way in the frontend.
I would suggest the following format:

// A general error returns errors that are not linked to any input field.
generalErrors: [
    {
        message: "Something general has occurred."
    }
],

// A field error returns an error that is linked to a body input field. 
// (eg name or description when creating a project)
inputErrors: [
     {
        input: "name",
        message: "Name cannot be longer than 3 characters."
     }
]

[iasoon]

👍 Maybe it would be an idea to maintain an OpenAPI spec, for maximal clarity? This would also be helpful when developing integrations with g2 later on.

[maartenvn]

+1 Maybe it would be an idea to maintain an OpenAPI spec, for maximal clarity? This would also be helpful when developing integrations with g2 later on.

There is already an OpenAPI (Swagger) spec available at the root :)