Adding /api/glossary

src/main/scala/code/api/util/APIUtil.scala

@@ -35,6 +35,7 @@ package code.api.util
 import java.io.InputStream
 import java.nio.charset.{Charset, StandardCharsets}
 import java.text.SimpleDateFormat
+import java.util
 import java.util.{Date, UUID}
 
 import code.api.Constant._
@@ -1168,6 +1169,144 @@ object APIUtil extends MdcLoggable {
   )
 
 
+  case class GlossaryItem(
+                           title: String,
+                           description: String
+                       )
+
+
+
+
+
+  val glossaryItems = ArrayBuffer[GlossaryItem]()
+
+
+
+  glossaryItems += GlossaryItem(
+    title = "Account",
+    description =
+      """The thing that tokens of value (money) come in and out of.
+        |An account has one or more `owners` which are `Users`.
+        |In the future, `Customers` may also be `owners`.
+        |An account has a balance in a specified currency and zero or more `transactions` which are records of successful movements of money.
+        |"""
+  )
+
+  glossaryItems += GlossaryItem(
+    title = "Account.account_id",
+    description =
+    """
+      |An identifier for the account that MUST NOT leak the account number or other identifier nomrally used by the customer or bank staff.
+      |It SHOULD be a UUID. It MUST be unique in combination with the BANK_ID. ACCOUNT_ID is used in many URLS so it should be considered public.
+      |(We do NOT use account number in URLs since URLs are cached and logged all over the internet.)
+      |In local / sandbox mode, ACCOUNT_ID is generated as a UUID and stored in the database.
+      |In non sandbox modes (Kafka etc.), ACCOUNT_ID is mapped to core banking account numbers / identifiers at the South Side Adapter level.
+      |ACCOUNT_ID is used to link Metadata and Views so it must be persistant and known to the North Side (OBP-API).
+    """)
+
+  glossaryItems += GlossaryItem(
+    title = "Bank",
+    description =
+    """
+      |The entity that represents the financial institution or bank within a financial group.
+      |Open Bank Project is a multi-bank API. Each bank resource contains basic identifying information such as name, logo and website.
+    """)
+
+
+  glossaryItems += GlossaryItem(
+    title = "Bank.bank_id",
+    description =
+    """
+      |An identifier that uniquely identifies the bank or financial institution on the OBP-API instance.
+      |
+      |It is typically a human (developer) friendly string for ease of identification.
+      |In sandbox mode it typically has the form financialinstitutuion.sequenceno.region.language. e.g. "bnpp-irb.01.it.it" however for production it could be the BIC of the institution.
+     """)
+
+  glossaryItems += GlossaryItem(
+    title = "Consumer",
+    description =
+    """
+      |The "consumer" of the API, i.e. the web, mobile or serverside "App" that calls on the OBP API on behalf of the end user (or system).
+      |
+      |Each Consumer has a consumer key and secrect which allows it to enter into secure communication with the API server.
+    """)
+
+  glossaryItems += GlossaryItem(
+    title = "Customer",
+    description =
+      """
+        |The legal entity that has the relationship to the bank. Customers are linked to Users via `User Customer Links`. Customer attributes include Date of Birth, Customer Number etc.
+        |
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "Customer.customer_id",
+    description =
+      """
+        |The identifier that MUST NOT leak the customer number or other identifier nomrally used by the customer or bank staff. It SHOULD be a UUID and MUST be unique in combination with BANK_ID.
+        |
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "Transaction",
+    description =
+      """
+        |Records of successful movements of money from / to an `Account`. OBP Transactions don't contain any "draft" or "pending" Transactions. (see Transaction Requests). Transactions contain infomration including type, description, from, to, currency, amount and new balance information.
+        |
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "Transaction Requests",
+    description =
+      """
+        |Transaction Requests are records of transaction / payment requests coming to the API. They may or may not result in Transactions (following authorisation, security challenges and sufficient funds etc.)
+        |
+        |A successful Transaction Request results in a Transaction.
+        |
+        |For more information [see here](https://github.com/OpenBankProject/OBP-API/wiki/Transaction-Requests)
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "User",
+    description =
+      """
+        |The entity that accesses the API with a login / authorisation token and has access to zero or more resources on the OBP API. The User is linked to the core banking user / customer at the South Side Adapter layer.
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "User.user_id",
+    description =
+      """
+        |An identifier that MUST NOT leak the user name or other identifier nomrally used by the customer or bank staff. It SHOULD be a UUID and MUST be unique on the OBP instance.
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "User.provider",
+    description =
+      """
+        |The name of the authentication service. e.g. the OBP hostname or kafka if users are authenticated over Kafka.
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "User.provider_id",
+    description =
+      """
+        |The id of the user given by the authenticaiton provider.
+      """)
+
+  glossaryItems += GlossaryItem(
+    title = "User Customer Links",
+    description =
+      """
+        |Link Users and Customers in a many to many relationship. A User can represent many Customers (e.g. the bank may have several Customer records for the same individual or a dependant). In this way Customers can easily be attached / detached from Users.
+      """)
+
+  def getGlossaryItems : List[GlossaryItem] = {
+    glossaryItems.toList
+  }
+
+
   /**
     *
     * This is the base class for all kafka outbound case class

src/main/scala/code/api/v1_2_1/APIMethods121.scala

@@ -104,7 +104,7 @@ trait APIMethods121 {
       "root",
       "GET",
       "/root",
-      "The root of the API",
+      "Get API Info",
       """Returns information about:
         |
         |* API version

src/main/scala/code/api/v2_2_0/APIMethods220.scala

@@ -774,9 +774,10 @@ trait APIMethods220 {
       "config",
       "GET",
       "/config",
-      "The configuration of the API",
+      "Get API Configuration",
       """Returns information about:
         |
+        |* API Config
         |* Akka ports
         |* Elastic search ports
         |* Cached function """,

src/main/scala/code/api/v3_0_0/APIMethods300.scala

@@ -1765,6 +1765,46 @@ trait APIMethods300 {
 
 
 
+   val exampleGlossaryItems = List(GlossaryItem(
+      title = "Title ",
+      description =
+        """
+          |Description.
+          |
+          |Goes here..
+        """))
+
+    def getExampleGlossaryItems : List[GlossaryItem] = {
+      exampleGlossaryItems.toList
+    }
+
+
+    resourceDocs += ResourceDoc(
+      getApiGlossary,
+      implementedInApiVersion,
+      "glossary",
+      "GET",
+      "/api/glossary",
+      "Get API Glossary",
+      """Returns the glossary of the API
+        |""",
+      emptyObjectJson,
+      JSONFactory300.createGlossaryItemsJsonV300(getExampleGlossaryItems),
+      List(UnknownError),
+      Catalogs(notCore, notPSD2, notOBWG),
+      apiTagApi :: Nil)
+
+    lazy val getApiGlossary : OBPEndpoint = {
+      case "api" :: "glossary" :: Nil JsonGet json => _ => {
+        val json = JSONFactory300.createGlossaryItemsJsonV300(getGlossaryItems)
+        Full(successJsonResponse(Extraction.decompose(json)))
+      }
+    }
+
+
+
+
+
     /* WIP
         resourceDocs += ResourceDoc(
           getOtherAccountsForBank,

src/main/scala/code/api/v3_0_0/JSONFactory3.0.0.scala

@@ -45,6 +45,7 @@ import code.entitlement.Entitlement
 import code.entitlementrequest.EntitlementRequest
 import code.model.dataAccess.ResourceUser
 import net.liftweb.common.{Box, Full}
+import org.pegdown.PegDownProcessor
 
 import scala.collection.immutable.List
 
@@ -393,7 +394,47 @@ case class EntitlementRequestJSON(entitlement_request_id: String, user: UserJson
 case class EntitlementRequestsJSON(entitlement_requests: List[EntitlementRequestJSON])
 case class CreateEntitlementRequestJSON(bank_id: String, role_name: String)
 
+
+
+case class GlossaryDescriptionJsonV300 (markdown: String, html: String)
+
+case class GlossaryItemJsonV300 (title: String,
+                                 description : GlossaryDescriptionJsonV300
+                                )
+
+case class GlossaryItemsJsonV300 (glossary_items: List[GlossaryItemJsonV300])
+
+
+
+import code.api.util.APIUtil.GlossaryItem
+
 object JSONFactory300{
+
+  // There are multiple flavours of markdown. For instance, original markdown emphasises underscores (surrounds _ with (<em>))
+  // But we don't want to have to escape underscores (\_) in our documentation
+  // Thus we use a flavour of markdown that ignores underscores in words. (Github markdown does this too)
+  // PegDown seems to be feature rich and ignores underscores in words by default.
+
+  // We return html rather than markdown to the consumer so they don't have to bother with these questions.
+  // Set the timeout: https://github.com/sirthias/pegdown#parsing-timeouts
+  val PegDownProcessorTimeout: Long = 1000*20
+  val pegDownProcessor : PegDownProcessor = new PegDownProcessor(PegDownProcessorTimeout)
+
+
+
+  def createGlossaryItemsJsonV300(glossaryItems: List[GlossaryItem]) : GlossaryItemsJsonV300 = {
+    GlossaryItemsJsonV300(glossary_items = glossaryItems.map(createGlossaryItemJsonV300))
+  }
+
+  def createGlossaryItemJsonV300(glossaryItem : GlossaryItem) : GlossaryItemJsonV300 = {
+    GlossaryItemJsonV300(
+      title = glossaryItem.title,
+      description = GlossaryDescriptionJsonV300 (markdown = glossaryItem.description.stripMargin, //.replaceAll("\n", ""),
+                                                  html = pegDownProcessor.markdownToHtml(glossaryItem.description.stripMargin).replaceAll("\n", "")
+      )
+    )
+  }
+
   //stated -- Transaction relevant methods /////
   def createTransactionsJson(transactions: List[ModeratedTransaction]) : TransactionsJsonV300 = {
     TransactionsJsonV300(transactions.map(createTransactionJSON))

src/main/scala/code/api/v3_0_0/OBPAPI3_0_0.scala

@@ -265,6 +265,7 @@ object OBPAPI3_0_0 extends OBPRestHelper with APIMethods130 with APIMethods140 w
                           Implementations3_0_0.getFirehoseAccountsAtOneBank ::
                           Implementations3_0_0.getEntitlementsForCurrentUser ::
                           Implementations3_0_0.getFirehoseTransactionsForBankAccount ::
+                          Implementations3_0_0.getApiGlossary ::
                           Nil