Implement /api/name-groups endpoint (#61)

Author: cdhorn

gramps_webapi/api/__init__.py

@@ -17,6 +17,7 @@
 from .resources.filters import FilterResource
 from .resources.media import MediaObjectResource, MediaObjectsResource
 from .resources.metadata import MetadataResource
+from .resources.name_groups import NameGroupsResource
 from .resources.note import NoteResource, NotesResource
 from .resources.person import PeopleResource, PersonResource
 from .resources.place import PlaceResource, PlacesResource
@@ -69,6 +70,12 @@ def register_endpt(resource: Type[Resource], url: str, name: str):
 # Token
 register_endpt(TokenResource, "/login/", "token")
 register_endpt(TokenRefreshResource, "/refresh/", "token_refresh")
+# Name Groups
+register_endpt(
+    NameGroupsResource, "/name-groups/<string:surname>/<string:group>", "set-name-group"
+)
+register_endpt(NameGroupsResource, "/name-groups/<string:surname>", "get-name-group")
+register_endpt(NameGroupsResource, "/name-groups/", "name-groups")
 # Bookmark
 register_endpt(BookmarkResource, "/bookmarks/<string:namespace>", "bookmark")
 register_endpt(BookmarksResource, "/bookmarks/", "bookmarks")

gramps_webapi/api/resources/name_groups.py

@@ -0,0 +1,45 @@
+"""Name Groups API resource."""
+
+from flask import Response, abort
+from gramps.gen.db.base import DbReadBase
+
+from ..util import get_dbstate
+from . import ProtectedResource
+from .emit import GrampsJSONEncoder
+
+
+class NameGroupsResource(ProtectedResource, GrampsJSONEncoder):
+    """Name group mappings resource."""
+
+    @property
+    def db_handle(self) -> DbReadBase:
+        """Get the database instance."""
+        return get_dbstate().db
+
+    def get(self, surname: str = None) -> Response:
+        """Get list of name group mappings."""
+        db_handle = self.db_handle
+        if surname is not None:
+            return self.response(
+                200,
+                {
+                    "surname": surname,
+                    "group": db_handle.get_name_group_mapping(surname),
+                },
+            )
+        result = db_handle.get_name_group_keys()
+        mappings = []
+        if result is not None:
+            for name in result:
+                mappings.append(
+                    {"surname": name, "group": db_handle.get_name_group_mapping(name)}
+                )
+        return self.response(200, mappings)
+
+    def post(self, surname: str = None, group: str = None) -> Response:
+        """Set a name group mapping."""
+        db_handle = self.db_handle
+        if surname is None or group is None or len(surname) == 0 or len(group) == 0:
+            abort(400)
+        db_handle.set_name_group_mapping(surname, group)
+        return self.response(201, {"surname": surname, "group": group})

gramps_webapi/data/apispec.yaml

@@ -47,6 +47,8 @@ tags:
   description: Access to note objects.
 - name: tags
   description: Access to tag objects.
+- name: name-groups
+  description: Access to name group mappings.
 - name: bookmarks
   description: Access to user bookmarks.
 - name: filters
@@ -1690,6 +1692,77 @@ paths:
         404:
           description: "Not Found: Tag not found."
 
+##############################################################################
+# Endpoint - NameGroups
+##############################################################################
+
+  /name-groups:
+    get:
+      tags:
+      - name-groups
+      summary: "Get a list of name group mappings."
+      operationId: getNameGroupMappings
+      security:
+        - Bearer: []
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            type: array
+            items:
+              $ref: "#/definitions/NameGroupMapping"
+        401:
+          description: "Unauthorized: Missing authorization header."
+
+  /name-groups/{surname}:
+    get:
+      tags:
+      - name-groups
+      summary: "Get name group mapping for a given surname."
+      operationId: getNameGroupMapping
+      security:
+        - Bearer: []
+      parameters:
+      - name: surname
+        in: path
+        required: true
+        type: string
+        description: "The surname for which to get the grouping."
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            $ref: "#/definitions/NameGroupMapping"
+        401:
+          description: "Unauthorized: Missing authorization header."
+
+  /name-groups/{surname}/{group}:
+    post:
+      tags:
+      - name-groups
+      summary: "Set name group mapping for a given surname."
+      operationId: setNameGroupMapping
+      security:
+        - Bearer: []
+      parameters:
+      - name: surname
+        in: path
+        required: true
+        type: string
+        description: "The surname to set the mapping for."
+      - name: group
+        in: path
+        required: true
+        type: string
+        description: "The group to map the surname to."
+      responses:
+        200:
+          description: "OK: Successful operation."
+          schema:
+            $ref: "#/definitions/NameGroupMapping"
+        401:
+          description: "Unauthorized: Missing authorization header."
+
 ##############################################################################
 # Endpoint - Bookmarks
 ##############################################################################
@@ -4200,3 +4273,19 @@ definitions:
         example:
           - e9027bf5e7f77551b12e7da3c77
           - e9027bf3de2402f9faaac001cef
+
+##############################################################################
+# Model - NameGroupMapping
+##############################################################################
+
+  NameGroupMapping:
+    type: object
+    properties:
+      surname:
+        description: "Surname to be grouped."
+        type: string
+        example: Fernández
+      group:
+        description: "Surname to be grouped with."
+        type: string
+        example: Fernandez

tests/test_endpoints/test_name_groups.py

@@ -0,0 +1,50 @@
+"""Tests for the /api/name-groups endpoint using example_gramps."""
+
+import unittest
+
+from jsonschema import RefResolver, validate
+
+from . import API_SCHEMA, get_test_client
+
+
+class TestNameGroups(unittest.TestCase):
+    """Test cases for the /api/name-groups endpoint."""
+
+    @classmethod
+    def setUpClass(cls):
+        """Test class setup."""
+        cls.client = get_test_client()
+
+    def test_name_groups_endpoint(self):
+        """Test name groups."""
+        # check response returned for name groups listing
+        result = self.client.get("/api/name-groups/")
+        self.assertEqual(result.json[0], {"surname": "Fernández", "group": "Fernandez"})
+        # check response returned for specific surname
+        result = self.client.get("/api/name-groups/Fernández")
+        self.assertEqual(result.json, {"surname": "Fernández", "group": "Fernandez"})
+        # check response setting incomplete new group mapping
+        result = self.client.post("/api/name-groups/Stephen")
+        self.assertEqual(result.status_code, 400)
+        result = self.client.post("/api/name-groups/Stephen/")
+        self.assertEqual(result.status_code, 404)
+        # check response setting new group mapping
+        result = self.client.post("/api/name-groups/Stephen/Steven")
+        self.assertEqual(result.status_code, 201)
+        # check response returned for surname group mapping just created
+        result = self.client.get("/api/name-groups/Stephen")
+        self.assertEqual(result.json, {"surname": "Stephen", "group": "Steven"})
+        result = self.client.get("/api/name-groups/Steven")
+        self.assertEqual(result.json, {"surname": "Steven", "group": "Steven"})
+
+    def test_name_groups_endpoint_schema(self):
+        """Test name groups against the name group schema."""
+        # check record conforms to expected schema
+        result = self.client.get("/api/name-groups/")
+        resolver = RefResolver(base_uri="", referrer=API_SCHEMA, store={"": API_SCHEMA})
+        for group in result.json:
+            validate(
+                instance=group,
+                schema=API_SCHEMA["definitions"]["NameGroupMapping"],
+                resolver=resolver,
+            )