Move all concept endpoints under /concepts (#193)

The old endpoints (narrower, ancestors, search, and suggest) are still available as deprecated aliases, but will be removed in version 3.0.
gbv · Apr 14, 2023 · 2ae498a · 2ae498a
1 parent 7d8bcd7
commit 2ae498a
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -58,10 +58,10 @@ JSKOS Server implements the JSKOS API web service and storage for [JSKOS] data s
   - [POST /concepts](#post-concepts)
   - [PUT /concepts](#put-concepts)
   - [DELETE /concepts](#delete-concepts)
-  - [GET /narrower](#get-narrower)
-  - [GET /ancestors](#get-ancestors)
-  - [GET /suggest](#get-suggest)
-  - [GET /search](#get-search)
+  - [GET /concepts/narrower](#get-conceptsnarrower)
+  - [GET /concepts/ancestors](#get-conceptsancestors)
+  - [GET /concepts/suggest](#get-conceptssuggest)
+  - [GET /concepts/search](#get-conceptssearch)
   - [GET /annotations](#get-annotations)
   - [GET /annotations/:\_id](#get-annotations_id)
   - [POST /annotations](#post-annotations)
@@ -1546,6 +1546,8 @@ Currently the same as `/voc/suggest` with parameter `format=jskos`.
 ### GET /data
 Returns data for a certain URI or URIs. Can return concept schemes, concepts, concordances, mappings, and annotations.
 
+**Note:** As of version 2.0, this endpoint was adjusted to return all types of items that are available in the database, instead of just concepts and concept schemes. The additional parameters, apart from `uri`, were also removed. For the previous behavior (only without returning concept schemes), see [GET /concepts](#get-concepts).
+
 * **URL Params**
 
   `uri=[uri]` URIs for concepts or concept schemes separated by `|`
@@ -1555,15 +1557,15 @@ Returns data for a certain URI or URIs. Can return concept schemes, concepts, co
   JSON array of [JSKOS Items]
 
 ### GET /concepts
-Returns detailed data for concepts or concept schemes. Note that there is no certain order to the result set (but it should be consistent across requests).
+Returns detailed data for concepts. Note that there is no certain order to the result set (but it should be consistent across requests).
 
 * **URL Params**
 
-  `uri=[uri]` URIs for concepts or concept schemes separated by `|`
+  `uri=[uri]` URIs for concepts separated by `|`
 
-  `notation=[notation]` notations for concepts or concept schemes separated by `|`
+  `notation=[notation]` notations for concepts separated by `|`
 
-  `voc=[uri]` filter by concept scheme URI (note that if `voc` is given, no concept schemes will be returned)
+  `voc=[uri]` filter by concept scheme URI
 
   `properties=[list]` with `[list]` being a comma-separated list of properties (currently supporting `ancestors`, `narrower`, and `annotations`)
 
@@ -1646,9 +1648,11 @@ Deletes a concept from the database.
 
   Status 204, no content.
 
-### GET /narrower
+### GET /concepts/narrower
 Returns narrower concepts for a concept.
 
+**Note:** The old `/narrower` endpoint is deprecated as of version 2.0 and will be removed in version 3.0.
+
 * **URL Params**
 
   `uri=[uri]` URI for a concept
@@ -1758,9 +1762,11 @@ Returns narrower concepts for a concept.
   ]
   ```
 
-### GET /ancestors
+### GET /concepts/ancestors
 Returns ancestor concepts for a concept.
 
+**Note:** The old `/ancestors` endpoint is deprecated as of version 2.0 and will be removed in version 3.0.
+
 * **URL Params**
 
   `uri=[uri]` URI for a concept
@@ -1813,9 +1819,11 @@ Returns ancestor concepts for a concept.
   ]
   ```
 
-### GET /suggest
+### GET /concepts/suggest
 Returns concept suggestions.
 
+**Note:** The old `/suggest` endpoint is deprecated as of version 2.0 and will be removed in version 3.0.
+
 * **URL Params**
 
   `search=[keyword|notation]` specifies the keyword or notation (prefix) to search for
@@ -1934,9 +1942,11 @@ Returns concept suggestions.
   ]
   ```
 
-### GET /search
+### GET /concepts/search
 Currently the same as `/suggest` with parameter `format=jskos`. Additionally, search supports the parameter `properties=[list]` as in the other concept methods.
 
+**Note:** The old `/search` endpoint is deprecated as of version 2.0 and will be removed in version 3.0.
+
 ### GET /annotations
 Returns an array of annotations. Each annotation has a property `id` under which the specific annotation can be accessed.
 

diff --git a/config/index.js b/config/index.js
@@ -201,12 +201,12 @@ Object.defineProperty(config, "status", { get: function() {
   status.config.baseUrl = baseUrl
   // Set all available endpoints to `null` first
   for (let type of [
+    "data",
     "schemes",
     "top",
     "voc-search",
     "voc-suggest",
     "concepts",
-    "data",
     "narrower",
     "ancestors",
     "suggest",
@@ -217,6 +217,7 @@ Object.defineProperty(config, "status", { get: function() {
   ]) {
     status[type] = null
   }
+  status.data = `${baseUrl}data`
   if (status.config.schemes) {
     // Add endpoints related to schemes
     status.schemes = `${baseUrl}voc`
@@ -227,11 +228,10 @@ Object.defineProperty(config, "status", { get: function() {
   if (status.config.concepts) {
     // Add endpoints related to concepts
     status.concepts = `${baseUrl}voc/concepts`
-    status.data = `${baseUrl}data`
-    status.narrower = `${baseUrl}narrower`
-    status.ancestors = `${baseUrl}ancestors`
-    status.suggest = `${baseUrl}suggest`
-    status.search = `${baseUrl}search`
+    status.narrower = `${baseUrl}concepts/narrower`
+    status.ancestors = `${baseUrl}concepts/ancestors`
+    status.suggest = `${baseUrl}concepts/suggest`
+    status.search = `${baseUrl}concepts/search`
   }
   if (status.config.mappings) {
     status.mappings = `${baseUrl}mappings`

diff --git a/routes/concepts.js b/routes/concepts.js
@@ -67,49 +67,57 @@ if (config.concepts.delete) {
   )
 }
 
-router.get(
-  "/narrower",
-  config.concepts.read.auth ? auth.main : auth.optional,
-  utils.supportDownloadFormats([]),
-  utils.wrappers.async(async (req) => {
-    return await conceptService.getNarrower(req.query)
-  }),
-  utils.addPaginationHeaders,
-  utils.adjust,
-  utils.returnJSON,
-)
+// Add these routes both with and without the /concepts prefix.
+// TODO for 3.0: The routes without should be deprecated in the next major release.
+// See also: https://github.com/gbv/jskos-server/issues/193#issuecomment-1508038432
 
-router.get(
-  "/ancestors",
-  config.concepts.read.auth ? auth.main : auth.optional,
-  utils.supportDownloadFormats([]),
-  utils.wrappers.async(async (req) => {
-    return await conceptService.getAncestors(req.query)
-  }),
-  utils.addPaginationHeaders,
-  utils.adjust,
-  utils.returnJSON,
-)
+for (const prefix of ["", "/concepts"]) {
 
-router.get(
-  "/suggest",
-  config.concepts.read.auth ? auth.main : auth.optional,
-  utils.supportDownloadFormats([]),
-  utils.wrappers.async(async (req) => {
-    return await conceptService.getSuggestions(req.query)
-  }),
-  utils.addPaginationHeaders,
-  utils.returnJSON,
-)
+  router.get(
+    prefix + "/narrower",
+    config.concepts.read.auth ? auth.main : auth.optional,
+    utils.supportDownloadFormats([]),
+    utils.wrappers.async(async (req) => {
+      return await conceptService.getNarrower(req.query)
+    }),
+    utils.addPaginationHeaders,
+    utils.adjust,
+    utils.returnJSON,
+  )
 
-router.get(
-  "/search",
-  config.concepts.read.auth ? auth.main : auth.optional,
-  utils.supportDownloadFormats([]),
-  utils.wrappers.async(async (req) => {
-    return await conceptService.search(req.query)
-  }),
-  utils.addPaginationHeaders,
-  utils.adjust,
-  utils.returnJSON,
-)
+  router.get(
+    prefix + "/ancestors",
+    config.concepts.read.auth ? auth.main : auth.optional,
+    utils.supportDownloadFormats([]),
+    utils.wrappers.async(async (req) => {
+      return await conceptService.getAncestors(req.query)
+    }),
+    utils.addPaginationHeaders,
+    utils.adjust,
+    utils.returnJSON,
+  )
+
+  router.get(
+    prefix + "/suggest",
+    config.concepts.read.auth ? auth.main : auth.optional,
+    utils.supportDownloadFormats([]),
+    utils.wrappers.async(async (req) => {
+      return await conceptService.getSuggestions(req.query)
+    }),
+    utils.addPaginationHeaders,
+    utils.returnJSON,
+  )
+
+  router.get(
+    prefix + "/search",
+    config.concepts.read.auth ? auth.main : auth.optional,
+    utils.supportDownloadFormats([]),
+    utils.wrappers.async(async (req) => {
+      return await conceptService.search(req.query)
+    }),
+    utils.addPaginationHeaders,
+    utils.adjust,
+    utils.returnJSON,
+  )
+
+}
diff --git a/views/base.ejs b/views/base.ejs
@@ -95,11 +95,11 @@
     <h3>Concepts</h3>
     <ul>
       <li>GET <a href="concepts">/concepts</a> - Returns detailed data for concepts or concept schemes (<a href="https://github.com/gbv/jskos-server#get-concepts" target="_blank">documentation</a>)</li>
-      <li>GET <a href="narrower">/narrower</a> - Returns narrower concepts for a concept (<a href="https://github.com/gbv/jskos-server#get-narrower" target="_blank">documentation</a>)</li>
-      <li>GET <a href="ancestors">/ancestors</a> - Returns ancestor concepts for a concept (<a href="https://github.com/gbv/jskos-server#get-ancestors" target="_blank">documentation</a>)</li>
-      <li>GET <a href="suggest">/suggest</a> - Returns concept suggestions (<a href="https://github.com/gbv/jskos-server#get-suggest" target="_blank">documentation</a>)</li>
-      <li>GET <a href="search">/search</a> - Concept search (<a href="https://github.com/gbv/jskos-server#get-search" target="_blank">documentation</a>)</li>
-      <% if (config.concepts.create) { %>
+      <li>GET <a href="concepts/narrower">/concepts/narrower</a> - Returns narrower concepts for a concept (<a href="https://github.com/gbv/jskos-server#get-conceptsnarrower" target="_blank">documentation</a>)</li>
+      <li>GET <a href="ancestors">/concepts/ancestors</a> - Returns ancestor concepts for a concept (<a href="https://github.com/gbv/jskos-server#get-conceptsancestors" target="_blank">documentation</a>)</li>
+      <li>GET <a href="suggest">/concepts/suggest</a> - Returns concept suggestions (<a href="https://github.com/gbv/jskos-server#get-conceptssuggest" target="_blank">documentation</a>)</li>
+      <li>GET <a href="search">/concepts/search</a> - Concept search (<a href="https://github.com/gbv/jskos-server#get-conceptssearch" target="_blank">documentation</a>)</li>
+    <% if (config.concepts.create) { %>
       <li>POST /concepts - Saves a concept or multiple concepts in the database (<% if (config.schemes.create.auth) { %>authentication needed, <% } %><a href="https://github.com/gbv/jskos-server#post-concepts" target="_blank">documentation</a>)</li>
       <% } %>
       <% if (config.concepts.update) { %>