REST API : GET for repositories & projects

[neo-garaix]

• New entrypoint api.php
• REST API
• We can navigate through the API thanks to swagger
• Swagger is implemented inside the test stack and accessible through http://localhost:8133
• CORS in nginx conf has been updated so we can test the API from the Swagger

Swagger

Some commands :

curl http://localhost:8130/api.php/admin/repositories

{
    "error code": 401,
    "error message": "Unauthorized. Basic authentication is required to access this resource."
}

curl http://localhost:8130/api.php/admin/repositories --user admin:admin

[
  {
    "key": "testsrepository",
    "label": "Tests repository",
    "path": "tests/"
  },
  {
    "key": "private",
    "label": "Private repository",
    "path": "CONFIDENTIAL/"
  },
  {
    "key": "badrepository",
    "label": "Repository with bad path",
    "path": "bad/"
  },
  {
    "key": "montpellier",
    "label": "Demo",
    "path": "demoqgis/"
  },
  {
    "key": "intranet",
    "label": "Demo - Intranet",
    "path": "demoqgis_intranet/"
  }
]

curl http://localhost:8130/api.php/admin/repositories/intranet --user admin:admin

{
  "key": "intranet",
  "label": "Demo - Intranet",
  "path": "demoqgis_intranet/",
  "allowUserDefinedThemes": "",
  "accessControlAllowOrigin": "",
  "rightsGroup": {
    "lizmap.tools.edition.use": [
      "admins",
      "Intranet demos group",
      "lizadmins"
    ],
    "lizmap.repositories.view": [
      "admins",
      "Intranet demos group",
      "lizadmins"
    ],
    "lizmap.tools.loginFilteredLayers.override": [
      "admins",
      "Intranet demos group",
      "lizadmins"
    ],
    "lizmap.tools.displayGetCapabilitiesLinks": [
      "admins",
      "Intranet demos group",
      "lizadmins"
    ],
    "lizmap.tools.layer.export": [
      "admins",
      "Intranet demos group",
      "lizadmins"
    ]
  }
}

curl http://localhost:8130/api.php/admin/repositories/intr --user admin:admin

{
    "error code": 404,
    "error message": "Repository not found. Please provide a valid repository."
}

curl -X POST http://localhost:8130/api.php/admin/repositories/intranet --user admin:admin

{
    "error code": 501,
    "error message": "This action is not implemented."
}

Funded by 3Liz

[rldhont]

A first review

[rldhont]

Second review

[rldhont]

@neo-garaix can you add an OpenAPI description ?

Here is a first version:

openapi: 3.0.4
info:
  title: Lizmap Admin API
  version: 3.8.0
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: The HTTP response code message
          example: Not Found
        status:
          type: integer
          format: int32
          description: the HTTP response code status
          example: 404
        message:
          type: string
          description: Message describing the error
          example: Resource not found. Please provide a valid entry.
    RepositoryMainData:
      type: object
      properties:
        key:
          type: string
        label:
          type: string
        path:
          type: string
    RepositoryRightsGroup:
      type: object
      properties:
        lizmap.tools.edition.use:
          type: array
          items:
            type: string
        lizmap.repositories.view:
          type: array
          items:
            type: string
        lizmap.tools.loginFilteredLayers.override:
          type: array
          items:
            type: string
        lizmap.tools.displayGetCapabilitiesLinks:
          type: array
          items:
            type: string
        lizmap.tools.layer.export:
          type: array
          items:
            type: string
    Repository:
      type: object
      properties:
        key:
          type: string
        label:
          type: string
        path:
          type: string
        allowUserDefinedThemes:
          type: boolean
        accessControlAllowOrigin:
          type: string
        rightsGroup:
          $ref: '#/components/schemas/RepositoryRightsGroup'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
paths:
  /admin/repositories:
    get:
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RepositoryMainData'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []
  /admin/repositories/{repository_key}:
    get:
      parameters:
        - name: repository_key
          in: path
          description: The repository key to get repository data.
          required: true
          schema:
            type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Repository'
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []

[Gustry]

Nice addition.

Can you add some tests ?
You can have a look to tests/end2end/playwright/requests-metadata.spec.js to have different examples.

Can you check also relevant docstrings within this PR ?

So later, it will be for the request ID 268 ?

[neo-garaix]

@Gustry

Can you add some tests ? You can have a look to tests/end2end/playwright/requests-metadata.spec.js to have different examples.

Ofc, next thing to do !

Can you check also relevant docstrings within this PR ?

Sorry but, I think I don't really understand what you mean by "relevant" :')

So later, it will be for the request ID 268 ?

Yes !

[Gustry]

Becoming good

[Gustry]

Just some minor comments, LGTM

[nworr]

1st review

[rldhont]

I think it is the last review

[neo-garaix]

Working on cleaning commit history

[neo-garaix]

Fixed openai description where a ref wasn't well written.

[Gustry]

LGTM, just some rephrasing that I'm gonna commits now

[3liz-bot]

The backport to release_3_8 failed:

The process '/usr/bin/git' failed with exit code 1

stderr

error: could not apply dec52b6f3... REFACTOR: get rights of a repository
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".
hint: Disable this message with "git config set advice.mergeConflict false"

stdout

Auto-merging lizmap/modules/admin/controllers/maps.classic.php
CONFLICT (content): Merge conflict in lizmap/modules/admin/controllers/maps.classic.php

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-release_3_8 release_3_8
# Navigate to the new working tree
cd .worktrees/backport-release_3_8
# Create a new branch
git switch --create backport-5486-to-release_3_8
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick dec52b6f37f088faab00da492de51bc447f3a133,304ef9d7ceca2bbcf72dac97f5fe9f46591dd4b0,2776959fab93dc0bbff826eec43d2145ad0a9345,54848fac0cc5a347c39b1e54dd4fad8929bedfb0,1eb6e01a90e3f0276f57e7e1794b8b9ff8f07e6b,babe13d30d4b95d6d3e9453822148e146d209453,3dd517daf66013d17f85d345a0af8cf0c332dc98,92d95113c90f51fad052f8429f9b297fefa105eb
# Push it to GitHub
git push --set-upstream origin backport-5486-to-release_3_8
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-release_3_8

Then, create a pull request where the base branch is release_3_8 and the compare/head branch is backport-5486-to-release_3_8.

[mdouchin]

I think we should declare the new api.php entrypoint here Like here
https://github.com/3liz/lizmap-gobsapi-module/blob/bf1c91fad9e7aa493af08449f95b0c6ab23a91cd/gobsapi/install/configure.php#L34
cc @rldhont @laurentj