Enhance mirror node rest API to query by token name (#968)

Signed-off-by: Ali  <[email protected]>
Signed-off-by: Michael Garber <[email protected]>
Co-authored-by: Steven Sheehy <[email protected]>
Co-authored-by: Michael Garber <[email protected]>
Co-authored-by: Nana Essilfie-Conduah <[email protected]>

HIP/hip-968.md

@@ -0,0 +1,101 @@
+---
+hip: 968
+title: Enhance mirror node rest API to query by token name
+author: Simi Hunjan <SimiHunjan>, Ali Nikan <@alinik4n>
+working-group: Steven Sheehy <@steven-sheehy>, Eric <ericleponner>, Simon <svienot>
+type: Standards Track
+category: Mirror
+needs-council-approval: Yes
+status: Last Call
+last-call-date-time: 2024-06-03T07:00:00Z
+created: 2024-04-19
+requested-by: Hashport, Bonzo Finance
+discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/pull/968
+updated: 2024-05-20
+---
+
+## Abstract
+
+This HIP provides the capability of querying tokens by token name in mirror node REST API and getting the corresponding token ID information.
+
+## Motivation
+
+To enhance user experience and allow blockchain explorers such as Hashscan to enable the capability of searching by token name, we want to add this functionality to the mirror node to support querying tokens by token name.
+This is a very common use case across other explorers in the larger ecosystem, and will allow retail users and developers to be able to search for a token by token name instead of token ID.
+
+## Rationale
+
+Many times a user may not know the exact token ID when searching for a token, but they know the name. This capability allow users to search by the name and will return results when there is a partial match or exact match. Community members from bridges, Dexes, etc. have been requesting for this for a while.
+
+## User stories
+
+- As a user of mirror node, I want to be able to query with a token name (e.g Sauce) and get the corresponding token ID and information.
+- As a user of mirror node, I want to be able to see full match and partial match to my search. (e.g when querying for Sauce, I want to see result for $sauce and $xsauce)
+- As a user of a Hedera explorer, I want to look up a token by searching for token name.
+
+## Specification
+
+The proposed enhancement involves adding  query parameters `name` to the existing route `/api/v1/tokens` to return information about a token.  This new capability only supports HTS tokens at this point and will not include ERC 20/721 tokens, further improvements will be introduced later to support ERC 20/721.
+
+**Multiple Query Results**
+
+Names assigned to tokens when tokens are created on the network are not unique. Therefore, many tokens with the same name can exist. Querying a token by a given name will return all the tokens that have the specified name defined in the token name.
+
+**Name Query Parameter**
+
+A new `name` query parameter will be added to search for tokens by their name. This query parameter will perform a case insensitive sub-string match. That is, it will search for token names that start with, contain, or end with the given value. The usual operators like `eq`, `gt`, `gte`, `lt, `lte`, and `ne` will not be supported.
+
+`/api/v1/tokens?name={value}`
+
+
+**Request**
+```
+/api/v1/tokens?name=exampleToken
+```
+**Example Request** 
+
+```
+GET /api/v1/tokens?limit=2&name=sauce
+```
+Note: if ```limit``` is not specified in the request, response will be limited to 25 by default
+
+**Response** 
+Note: Most fields omitted for brevity
+
+```json
+{
+  "tokens": [{
+      "name": "SAUCE",
+      "symbol": "SAUCE",
+      "token_id": "0.0.731861"
+    }, {
+      "name": "xSAUCE",
+      "symbol": "XSAUCE",
+      "token_id": "0.0.1460200"
+    }
+  ],
+  "links": {
+    "next": "/api/v1/tokens?limit=2&name=sauce&token.id=gt:0.0.1460200"
+  }
+}
+```
+
+## **Backwards Compatibility**
+
+The change is backwards compatible as it is simply adding two query parameters to an existing route. The data required to filter by name is already stored in the mirror node.
+
+## Security Implications
+
+Full text search indices can slow down ingest performance if the same lexeme shows up in many token names.
+
+## Rejected Ideas
+
+- Searching token by symbol.
+
+## References
+
+https://mainnet-public.mirrornode.hedera.com/api/v1/docs/#/tokens/listTokens
+
+## Copyright/license
+
+This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](https://www.notion.so/LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)