# Common Terms and Conventions Used

The Reference Architecture Team have made use of Common Terms and Conventions throughout the design and documentation for the Mojaloop 2.0 Reference Architecture model.

Please make use of this list to familiarise yourself with any terms that may be unfamiliar, or forgotten. The list includes references to third-party reference articles and documents that are listed in the Further Reading section of this document.

Convention/Term	Description
Actors	Human or external system Use Case participant. All Use Cases are driven by Actors.
BC	Bounded Context: A bounded-context is a component of Design-Driven Development and typically contains a single, or multiple subdomains. Bounded Contexts are Solution Space entities, and contain a single solution applicable to a single, or multiple, subdomain/s. (For additional insights, please see: DDD Inspired Architecture Overview section in the Solution Space overview, or our Further Reading: Reference Articles and Documents)
UC	Use Case: A Use Case is a list of actions or steps describing interactions between an Actor (human or external system) and a system to achieve a particular objective. An example of a Use Case from Mojaloop is “Perform Transfer with Payee Confirmation”. (For additional insights, please see the “Use Case”, Wikipedia article reference in the Further Reading: Reference Articles and Documents section of this document)
Sync	Synchronous communications, one or two way, part of the originating process. Signified by a solid line in the UC schematics. Typically used for Messages that need to be included in a particular UC workflow in order for it to execute successfully. An example of synch Messaging is a query from the Transfers BC to the Participant Lifecycle Management BC to get Participant data if not cached to complete a Transfer request.
Async	Asynchronous communications, one or two way, not part of the originating process. Signified by a dotted line in the UC schematics. Typically used for Events which are used to indicate something that has happened, and is immutable and won’t change, for example callback reports.
POST	Utilized to create new resources. In particular, it’s used to create subordinate resources. That is, subordinate to some other (e.g. parent) resource. IOW, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc. On successful creation, the system will return a Location header with a link to the newly-created resource with the 201 HTTP status. (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
GET	Utilized to read (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
PUT	Utilized for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. In some instances PUT can also be utilized to create new resources, however owing to complexity, this is not recommended (POST should be used instead). (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
200 (OK)	HTTP Status code indicating “Success”. The request has succeeded. Typically the information returned with the status code is dependent upon the method used in the request. For example, in Mojaloop the methods most commonly used are POST, GET, PUT. For POST, the response would describe or include the result of the action, for GET the requested entity is sent in the response, and for a PUT request, the response would be similar to a POST request. (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
201 (Created)	HTTP Status code indicating “Created” or fulfilled. This means that the request has been fulfilled and that the new resource is accessible via the URI returned in the entity response. The origin server will create the resource before returning a 201 code, and if it is not able to do so immediately, will return a 202 (Accepted) instead. (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
202 (Accepted)	HTTP Status code indicating that a request has been accepted for processing, but has not been completed. The request may or may not be acted upon when system allows as it may be disallowed when processing occurs. As the operation is asynchronous, there is also not facility for resending the status code, regardless of outcome. The 202 response is deliberately non-committal to enable a request to be processes without requiring the agent to remain connected until such time as it does. The response should include an indication of system status, and either a pointer to a monitoring platform, or an indication of when the request will be acted upon. (For additional insights, please see the “Restful API Tutor”, document reference in the Further Reading: Reference Articles and Documents section of this document)
OHS	Open Host Service: Describes documentation of methods to employ to successfully integrate downstream systems into an existing upstream system without requiring any mods to be made to the upstream platform. Typically support is provided for multiple client-types, and will have no particular interest in specific clients. The downstream system will be required to understand the upstream published documentation. OHS and PL are commonly paired by upstream systems. Currently utilized in the following entities: FSPIOP External API; ISO External API; Notifications & Alerts BC; PISP ML External API; PISP ISO External API; Scheduling BC; Transfers & Transactions BC; Agreement (Quoting) BC; Accounts & Balances BC; Settlements BC; Participant Lifecycle Management; Account Lookup & Discovery BC) (For additional insights, please see the “Strategic Domain-Driven Design”, article reference in the Further Reading: Reference Articles and Documents section of this document)
PL	Published Language: Described as the closest relative to open host service and often used together. PL uses a documented language, for example XML, for basic I/O operations to the system for which it is being utilized. No particular library or implementation spec is required for connecting to the system provided one conforms to the published language. It is not necessary to run only web services with a Published Language. One can also do things like upload a file to a particular folder, which then triggers an operation that stores the content of the file at an application specified location. Currently utilized in the following entities: FSPIOP External API; ISO External API (For additional insights please see the “Strategic Domain-Driven Design”, article reference in the Further Reading: Reference Articles and Documents section of this document))