From 8e3519028d38c3fa980cc693b3edc1daed3aee7f Mon Sep 17 00:00:00 2001 From: Simon Redfern Date: Tue, 20 Feb 2018 22:35:45 +0100 Subject: [PATCH] Adding /api/glossary --- src/main/scala/code/api/util/APIUtil.scala | 139 ++++++++++++++++++ .../scala/code/api/v1_2_1/APIMethods121.scala | 2 +- .../scala/code/api/v2_2_0/APIMethods220.scala | 3 +- .../scala/code/api/v3_0_0/APIMethods300.scala | 40 +++++ .../code/api/v3_0_0/JSONFactory3.0.0.scala | 41 ++++++ .../scala/code/api/v3_0_0/OBPAPI3_0_0.scala | 1 + 6 files changed, 224 insertions(+), 2 deletions(-) diff --git a/src/main/scala/code/api/util/APIUtil.scala b/src/main/scala/code/api/util/APIUtil.scala index 5c7f07e4b..c22b8dcc6 100644 --- a/src/main/scala/code/api/util/APIUtil.scala +++ b/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 diff --git a/src/main/scala/code/api/v1_2_1/APIMethods121.scala b/src/main/scala/code/api/v1_2_1/APIMethods121.scala index 2f5e4aba8..4b2105425 100644 --- a/src/main/scala/code/api/v1_2_1/APIMethods121.scala +++ b/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 diff --git a/src/main/scala/code/api/v2_2_0/APIMethods220.scala b/src/main/scala/code/api/v2_2_0/APIMethods220.scala index 08dbcc7b5..b60a383f7 100644 --- a/src/main/scala/code/api/v2_2_0/APIMethods220.scala +++ b/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 """, diff --git a/src/main/scala/code/api/v3_0_0/APIMethods300.scala b/src/main/scala/code/api/v3_0_0/APIMethods300.scala index eb695c3b5..22017d035 100644 --- a/src/main/scala/code/api/v3_0_0/APIMethods300.scala +++ b/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, diff --git a/src/main/scala/code/api/v3_0_0/JSONFactory3.0.0.scala b/src/main/scala/code/api/v3_0_0/JSONFactory3.0.0.scala index c7d15ae1b..c87b19b7d 100644 --- a/src/main/scala/code/api/v3_0_0/JSONFactory3.0.0.scala +++ b/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 ()) + // 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)) diff --git a/src/main/scala/code/api/v3_0_0/OBPAPI3_0_0.scala b/src/main/scala/code/api/v3_0_0/OBPAPI3_0_0.scala index 46bb57e65..30c5806a2 100644 --- a/src/main/scala/code/api/v3_0_0/OBPAPI3_0_0.scala +++ b/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