Feature: Tags

README.md

@@ -74,12 +74,12 @@ Note that some apps require certain environment variables to be set, which are d
 
 Apps will run on the following ports:
 
-| App Project                     | Port   |
-| ------------------------------- | ------ |
-| [api](./apps/api)               | `3003` |
-| [contribute](./apps/contribute) | `3002` |
-| [edit](./apps/edit)             | `3001` |
-| [www](./apps/www)               | `3000` |
+| App Project                     | Port                              |
+| ------------------------------- | --------------------------------- |
+| [api](./apps/api)               | `3003` (HTTP) and `3004` (Lambda) |
+| [contribute](./apps/contribute) | `3002`                            |
+| [edit](./apps/edit)             | `3001`                            |
+| [www](./apps/www)               | `3000`                            |
 
 ## Releasing versions
 

apps/api-docs/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New endpoints: `/imagetags`, `/nodes/{uuid}/imagetags`.
+- New property: `Image.tags`.
+- New query parameter for image list: `filter_tags`.
+
 ### Changed
 
 ### Deprecated

apps/api-docs/public/v2/openapi.yaml

@@ -28,6 +28,8 @@ tags:
     description: Methods related to phylogenetic nodes.
   - name: search
     description: Searches for entities (images and nodes).
+  - name: tags
+    description: Methods related to tags.
   - name: uploads
     description: Methods related to file uploads.
 servers:
@@ -193,7 +195,7 @@ components:
       description: |
         Limits results to entities within the specified collection.
 
-        Cannot be used alongside other `filter_*` parameters (except `filter_license_*` for images).
+        Cannot be used alongside `filter_clade`, `filter_contributor`, `filter_name`, or `filter_node`.
       schema:
         example: "060f03a9-fafd-4d08-81d1-b8f82080573f"
         pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
@@ -345,6 +347,16 @@ components:
         example: "8f901db5-84c1-4dc0-93ba-2300eeddf4ab"
         format: uuid
         type: string
+    filter_tags:
+      name: filter_tags
+      in: query
+      required: false
+      description: |
+        Limits results to images associated with one or more tags, comma-separated.
+      schema:
+        example: "male,subadult"
+        format: "^[a-z0-9 -]{2,}(,[a-z0-9 -]{2,})*$"
+        type: string
     namespace:
       name: namespace
       in: path
@@ -627,6 +639,7 @@ components:
             - modified
             - modifiedFile
             - sponsor
+            - tags
           type: object
           properties:
             attribution:
@@ -649,6 +662,12 @@ components:
               type: string
               example: "Patron Name"
               nullable: true
+            tags:
+              type: array
+              items:
+                example: "juvenile"
+                format: "^[a-z0-9 -]{2,}$"
+                type: string
             unlisted:
               description: If true, this image will not appear in lists.
               type: boolean
@@ -1342,6 +1361,7 @@ paths:
         - $ref: "#/components/parameters/filter_modifiedFile_before"
         - $ref: "#/components/parameters/filter_name"
         - $ref: "#/components/parameters/filter_node"
+        - $ref: "#/components/parameters/filter_tags"
         - $ref: "#/components/parameters/page"
       responses:
         "200":
@@ -1398,6 +1418,49 @@ paths:
           $ref: "#/components/responses/406"
         "410":
           $ref: "#/components/responses/410"
+  /imagetags:
+    get:
+      operationId: getImageTags
+      summary: Returns a list of all image tags.
+      tags:
+        - images
+        - tags
+      description:
+        Returns a list of all tags currently in use for images.
+      parameters:
+        - $ref: "#/components/parameters/Accept"
+        - $ref: "#/components/parameters/build"
+      responses:
+        "200":
+          description: List of tags.
+          headers:
+            Content-Type:
+              $ref: "#/components/headers/Content-Type"
+          content:
+            application/vnd.phylopic.v2+json:
+              schema:
+                type: object
+                required:
+                  - build
+                  - tags
+                properties:
+                  build:
+                    type: number
+                    format: integer
+                  tags:
+                    type: array
+                    items:
+                      example: "colony"
+                      format: "^[a-z0-0 -]{2,}$"
+                      type: string
+        "307":
+          $ref: "#/components/responses/307"
+        "400":
+          $ref: "#/components/responses/400"
+        "406":
+          $ref: "#/components/responses/406"
+        "410":
+          $ref: "#/components/responses/410"
   /licenses:
     get:
       operationId: getLicenses
@@ -1427,8 +1490,6 @@ paths:
           $ref: "#/components/responses/307"
         "400":
           $ref: "#/components/responses/400"
-        "404":
-          $ref: "#/components/responses/404"
         "406":
           $ref: "#/components/responses/406"
         "410":
@@ -1554,6 +1615,41 @@ paths:
           $ref: "#/components/responses/406"
         "410":
           $ref: "#/components/responses/410"
+  /nodes/{uuid}/imagetags:
+    get:
+      operationId: getNodeImageTags
+      summary: Returns a list of all image tags in use for this clade.
+      description: |
+        Returns a list of all tags associated with images associated with this node or any descendant of this node.
+      tags:
+        - images
+        - nodes
+        - tags
+      parameters:
+        - $ref: "#/components/parameters/Accept"
+        - $ref: "#/components/parameters/build"
+      responses:
+        "200":
+          description: List of tags.
+          headers:
+            Content-Type:
+              $ref: "#/components/headers/Content-Type"
+          content:
+            application/vnd.phylopic.v2+json:
+              schema:
+                type: array
+                items:
+                  type: string
+        "307":
+          $ref: "#/components/responses/307"
+        "400":
+          $ref: "#/components/responses/400"
+        "404":
+          $ref: "#/components/responses/404"
+        "406":
+          $ref: "#/components/responses/406"
+        "410":
+          $ref: "#/components/responses/410"
   /nodes/{uuid}/lineage:
     get:
       operationId: getLineage

apps/api/CHANGELOG.md

@@ -9,12 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New endpoints: `/imagetags`, `/nodes/{uuid}/imagetags`.
+- New property: `Image.tags`.
+- New query parameter for image list: `filter_tags`.
+
 ### Changed
 
+- Upgraded `@aws-sdk` dependencies.
+
 ### Deprecated
 
 ### Fixed
 
+- The `build` query parameter was missing in the Serverless configuration for several endpoints.
+- In `dev` mode, the lambda process was using the same port as `contribute`.
+
 ### Removed
 
 ### Security

apps/api/README.md

@@ -56,6 +56,8 @@ To run the API on your local machine, on port `3003`:
 yarn dev
 ```
 
+(This will run the lambda on port `3004`.)
+
 ## Deploying
 
 To deploy to `api.phylopic.org` (if you have [AWS Command Line Interface](https://aws.amazon.com/cli/) set up with proper credentials):

apps/api/package.json

@@ -7,7 +7,7 @@
         "url": "https://github.com/keesey/phylopic/issues"
     },
     "dependencies": {
-        "@aws-sdk/client-s3": "^3.675.0",
+        "@aws-sdk/client-s3": "^3.732.0",
         "@phylopic/api-models": "*",
         "@phylopic/utils": "*",
         "jsonwebtoken": "^9.0.2",
@@ -34,13 +34,13 @@
     "license": "MIT",
     "name": "@phylopic/api",
     "peerDependencies": {
-        "@aws-sdk/signature-v4-crt": "^3.674.0"
+        "@aws-sdk/signature-v4-crt": "^3.731.0"
     },
     "private": true,
     "scripts": {
         "clean": "rm -rf .serverless && rm -rf .turbo && rm -rf .webpack && rm -rf node_modules",
         "deploy": "sls deploy",
-        "dev": "sls offline --httpPort 3003",
+        "dev": "sls offline --httpPort 3003 --lambdaPort 3004",
         "lint": "eslint --fix ./**/*.[jt]s"
     },
     "version": "2.7.1"

apps/api/serverless.yml

@@ -261,6 +261,7 @@ functions:
                               filter_modifiedFile_before: false
                               filter_name: false
                               filter_node: false
+                              filter_tags: false
                               embed_contributor: false
                               embed_generalNode: false
                               embed_items: false
@@ -293,6 +294,26 @@ functions:
                               embed_generalNode: false
                               embed_nodes: false
                               embed_specificNode: false
+            - http:
+                  cors:
+                      allowCredentials: true
+                      origin: "*"
+                      headers:
+                          - Accept
+                          - Authorization
+                          - Content-Type
+                          - X-Amz-Date
+                          - X-Amz-Security-Token
+                          - X-Amz-User-Agent
+                          - X-Api-Key
+                  path: imagetags
+                  method: get
+                  request:
+                      parameters:
+                          headers:
+                              accept: false
+                          querystrings:
+                              build: false
             - http:
                   cors:
                       allowCredentials: true
@@ -360,9 +381,32 @@ functions:
                           paths:
                               uuid: true
                           querystrings:
+                              build: false
                               embed_childNodes: false
                               embed_parentNode: false
                               embed_primaryImage: false
+            - http:
+                  cors:
+                      allowCredentials: true
+                      origin: "*"
+                      headers:
+                          - Accept
+                          - Authorization
+                          - Content-Type
+                          - X-Amz-Date
+                          - X-Amz-Security-Token
+                          - X-Amz-User-Agent
+                          - X-Api-Key
+                  path: "nodes/{uuid}/imagetags"
+                  method: get
+                  request:
+                      parameters:
+                          headers:
+                              accept: false
+                          paths:
+                              uuid: true
+                          querystrings:
+                              build: false
             - http:
                   cors:
                       allowCredentials: true
@@ -384,6 +428,7 @@ functions:
                           paths:
                               uuid: true
                           querystrings:
+                              build: false
                               embed_childNodes: false
                               embed_items: false
                               embed_parentNode: false
@@ -411,6 +456,7 @@ functions:
                               namespace: true
                               objectID: true
                           querystrings:
+                              build: false
                               embed_childNodes: false
                               embed_parentNode: false
                               embed_primaryImage: false
@@ -466,6 +512,7 @@ functions:
                               authority: true
                               namespace: true
                           querystrings:
+                              build: false
                               embed_childNodes: false
                               embed_parentNode: false
                               embed_primaryImage: false

apps/api/src/entities/image/addFilterToQuery.ts

@@ -31,5 +31,21 @@ const addFilterToQuery = (params: ImageListParameters, builder: QueryConfigBuild
     if (params.filter_modifiedFile_before !== undefined) {
         builder.add("AND modified_file<=$::timestamp without time zone", [params.filter_modifiedFile_before])
     }
+    if (params.filter_tags) {
+        builder.add("AND ")
+        const tags = params.filter_tags.split(",")
+        if (tags.length > 1) {
+            builder.add("(")
+        }
+        tags.forEach((tag, index) => {
+            if (index > 0) {
+                builder.add(" OR ")
+            }
+            builder.add("$::character varying=ANY(image.tags)", [tag])
+        })
+        if (tags.length > 1) {
+            builder.add(")")
+        }
+    }
 }
 export default addFilterToQuery