diff --git a/docs/community/documentation/api-documentation.md b/docs/community/documentation/api-documentation.md index c1c8f8174..fc07d559b 100644 --- a/docs/community/documentation/api-documentation.md +++ b/docs/community/documentation/api-documentation.md @@ -1,29 +1,71 @@ # API Documentation -All APIs should be documented in RAML or Swagger, see Architecture-Documentation-Guidelines\]\(Architecture-Documentation-Guidelines.md\) +## Overview +Mojaloop provides a set of APIs that enable interoperable financial transactions. Proper API documentation is crucial for developers to understand and integrate with Mojaloop effectively. +All Mojaloop APIs must be documented using either: +- **RAML** (RESTful API Modeling Language) +- **OpenAPI/Swagger** (preferred for new APIs) -**Section Headings** +## API Documentation Standards + +### Format Requirements + +1. All API endpoints must include: + - Complete endpoint URL pattern + - HTTP method (GET, POST, PUT, DELETE, etc.) + - Request parameters and their data types + - Request body schema (when applicable) + - Response schema for each status code + - Error codes and descriptions + - Authentication requirements + +2. Include practical examples for both requests and responses + +3. Document all API versions with clear change logs between versions + +## Documentation Style + +### Section Headings * Do not number headings - for example, "Prepare and Fulfill", not "C - Prepare and Fulfill" -* Make sure section headings \(\# \) match the heading to which they correspond in the comprehensive PDF \(built from the [dactyl config file](https://github.com/Mojaloop/Docs/blob/master/ExportDocs/dactyl-config.yml)\) +* Make sure section headings match the heading to which they correspond in the comprehensive documentation * Do not include the word "documentation" in headings -#### Retrievability +### Organization and Accessibility * For sections that contain many subsections of endpoints or methods, provide a table of contents at the beginning of the section -* Don't say the word project; use component, microservice, interfaces, etc +* Group related endpoints together logically +* Use consistent terminology throughout the documentation +* Instead of the word "project," use a specific noun such as component, microservice, or interface + +### Procedures + +* Introduce procedures with H3 (`###`) or H4 (`####`) headers (not H2 (`##`)) +* Do not use numbers in procedure section headings +* Use ordered-list formatting for procedure steps, for example: + 1. Step 1 + 2. Step 2 + 3. Step 3 + +## API Documentation Tools + +The Mojaloop community recommends these tools for API documentation: + +- **Swagger UI**: For interactive OpenAPI documentation +- **ReDoc**: For more readable static documentation +- **Postman Collections**: For shareable API examples and testing -#### Language +## Integration with Core Documentation -Instead of the word "project," use a specific noun such as component, microservice, or interface. +API documentation should be: +1. Version-controlled alongside the code +2. Published to the main documentation site +3. Kept up-to-date as the API evolves -#### Procedures +## Resources -* Introduce procedures with H3 \(\#\#\#\) or H4 \(\#\#\#\#\) headers \(not H2 \(\#\#\)\). -* Do not use numbers in procedure section headings. -* Use ordered-list tagging for procedure steps. For example: -* Step 1 -* Step 2 -* Step 2 +- [Architecture Documentation Guidelines](https://docs.mojaloop.io/technical/architecture/architecture-documentation-guidelines.html) +- [OpenAPI Specification](https://swagger.io/specification/) +- [RAML Specification](https://raml.org/) diff --git a/docs/community/faqs.md b/docs/community/faqs.md index 71ac45b77..47d7138ca 100644 --- a/docs/community/faqs.md +++ b/docs/community/faqs.md @@ -1,9 +1,66 @@ -# Using Vue in Markdown +# Frequently Asked Questions -## Browser API Access Restrictions +## General Questions -Because VuePress applications are server-rendered in Node.js when generating static builds, any Vue usage must conform to the [universal code requirements](https://ssr.vuejs.org/en/universal.html). In short, make sure to only access Browser / DOM APIs in `beforeMount` or `mounted` hooks. +### What is Mojaloop? +Mojaloop is an open-source software project that provides a blueprint for payment interoperability between banks, payment providers, and other financial services companies. It's designed to serve the needs of the poor by connecting digital financial service providers and customers. -If you are using or demoing components that are not SSR friendly (for example containing custom directives), you can wrap them inside the built-in `` component: +### Who created Mojaloop? +Mojaloop was created by the Bill & Melinda Gates Foundation's Financial Services for the Poor program. It was built in collaboration with technology partners including Ripple, Dwolla, ModusBox, Software Group, and Crosslake Technologies. -## +### Is Mojaloop a payment system? +No, Mojaloop is not a payment system itself. It is a set of open-source software components that can be used to build interoperable payment systems. These components provide a blueprint for how digital financial services can connect with each other. + +### Is Mojaloop free to use? +Yes, Mojaloop is open-source software released under the Apache 2.0 license, which means it is free to use, modify, and distribute. + +## Technical Questions + +### What technologies does Mojaloop use? +Mojaloop primarily uses technologies such as Node.js, MongoDB, and Kubernetes. It follows a microservices architecture and implements the Level One Project's principles for financial inclusion. + +### How does Mojaloop ensure security? +Mojaloop implements various security measures including: +- End-to-end encryption for transactions +- Digital signatures for authenticity +- OAuth 2.0 for API security +- Role-based access controls +- Secure logging and audit trails + +### Can Mojaloop integrate with existing payment systems? +Yes, Mojaloop is designed to integrate with existing payment systems through its open API architecture. It can connect to banks, mobile money providers, and other financial service providers. + +## Implementation Questions + +### What do I need to implement Mojaloop? +To implement Mojaloop, you need: +- Technical expertise in distributed systems +- Understanding of financial regulations in your target market +- Infrastructure to host the components +- Partners (banks, mobile money providers) to connect to the system + +### How long does it take to implement Mojaloop? +Implementation time varies based on the complexity of the deployment, regulatory environment, and existing infrastructure. Typically, a basic implementation can take 6-12 months. + +### Where has Mojaloop been implemented? +Mojaloop has been implemented or is being implemented in several countries, including Tanzania, Kenya, Uganda, and others. The Mojaloop community maintains an updated list of implementations on their website. + +## Community Questions + +### How can I contribute to Mojaloop? +You can contribute to Mojaloop by: +- Contributing code on GitHub +- Participating in community calls and meetings +- Testing new releases +- Writing or improving documentation +- Sharing your implementation experiences + +### Where can I get help with Mojaloop? +You can get help with Mojaloop through: +- The Mojaloop Slack community +- The Mojaloop GitHub repositories +- Community calls and working groups +- The Mojaloop website documentation + +### How often is Mojaloop updated? +Mojaloop follows a regular release cycle with both planned feature releases and security updates. Major versions are typically released every few months, with minor updates and patches more frequently. diff --git a/docs/quickstarts/README.md b/docs/quickstarts/README.md index ee06bcdbe..c8721a804 100644 --- a/docs/quickstarts/README.md +++ b/docs/quickstarts/README.md @@ -1,10 +1,11 @@ -# Your First Action +# Your First Action with Mojaloop To help get you started with Mojaloop, select which of the options below best suits your needs: 1. [View the quickstarts](/1-overview/) -1. [Watch a demo](/99-demos/) -1. [Read the documentation](/1-overview/) -1. [Test out Mojaloop APIs](/1-overview/#apis) -1. [Take a training program](/3-guides/1_dfsp_setup/) -1. [Contribute to Mojaloop](https://docs.mojaloop.io/documentation/) \ No newline at end of file +2. [Developer Quickstart Guide](./developer-quickstart.md) +3. [Watch a demo](/99-demos/) +4. [Read the documentation](/1-overview/) +5. [Test out Mojaloop APIs](/1-overview/#apis) +6. [Take a training program](/3-guides/1_dfsp_setup/) +7. [Contribute to Mojaloop](https://docs.mojaloop.io/documentation/) \ No newline at end of file diff --git a/docs/quickstarts/developer-quickstart.md b/docs/quickstarts/developer-quickstart.md new file mode 100644 index 000000000..2e84c6e46 --- /dev/null +++ b/docs/quickstarts/developer-quickstart.md @@ -0,0 +1,129 @@ +# Developer Quickstart Guide + +This guide will help you set up a local Mojaloop development environment. Follow these steps to get Mojaloop running on your machine for development and testing purposes. + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- **Docker and Docker Compose** (latest stable version) +- **Node.js** (v14.x or later) +- **Git** (latest version) +- **Kubernetes CLI (kubectl)** (latest stable version) +- **Helm** (v3.x) +- **Postman** (for API testing) + +## Setting Up Your Environment + +### Step 1: Clone the Mojaloop Repository + +```bash +# Create a directory for Mojaloop +mkdir mojaloop && cd mojaloop + +# Clone the main repository +git clone https://github.com/mojaloop/mojaloop.git + +# Navigate to the cloned repository +cd mojaloop +``` + +### Step 2: Install the Mojaloop CLI + +The Mojaloop CLI helps you manage your local development environment: + +```bash +# Install the Mojaloop CLI globally +npm install -g @mojaloop/ml-cli + +# Verify the installation +ml-cli --version +``` + +### Step 3: Start the Local Environment + +Use Docker Compose to start a local development environment: + +```bash +# Navigate to the docker-compose directory +cd docker-compose + +# Start the environment +docker-compose up -d +``` + +This will start all the necessary services including: +- Central ledger +- Central settlement +- Account lookup service +- Quoting service +- Mock services for testing + +### Step 4: Verify the Installation + +To verify that your local environment is running correctly: + +```bash +# Check all containers are running +docker ps + +# Verify API access +curl http://localhost:3000/health +``` + +You should see a response indicating the services are healthy. + +## Running Your First Test Transfer + +### Step 1: Import Postman Collection + +1. Open Postman +2. Import the Postman collection from `./postman/mojaloop-local-test.postman_collection.json` +3. Set up the environment variables using the provided `./postman/mojaloop-local.postman_environment.json` + +### Step 2: Execute the Test Scenario + +1. In Postman, open the "Mojaloop Local Test" collection +2. Run the "End-to-End Transfer" folder +3. The collection will execute a series of requests to: + - Register participants + - Set up endpoints + - Perform party lookup + - Create and fulfill quotes + - Execute a transfer + +### Step 3: Monitoring the Transfer + +You can monitor the transfer in real-time using the logs: + +```bash +# View logs for the central ledger +docker logs -f ml-service-central-ledger +``` + +## Next Steps + +Now that you have a working Mojaloop environment, you can: + +1. **Explore the APIs**: Use Swagger UI at http://localhost:3000/swagger to explore all available APIs +2. **Modify a component**: Try making a small change to one of the services and see it take effect +3. **Run the automated tests**: Execute `npm test` in any component directory +4. **Check out the architecture**: Review the architecture documentation at `/docs/technical/architecture` + +## Troubleshooting + +If you encounter issues: + +1. **Services not starting**: Check Docker logs with `docker-compose logs` +2. **API errors**: Ensure all services are healthy with `curl http://localhost:3000/health` +3. **Database connection issues**: Verify database services are running with `docker ps | grep mysql` + +## Getting Help + +If you need assistance: + +1. **Join the Slack community**: [Mojaloop Slack](https://mojaloop-slack.herokuapp.com/) +2. **Check GitHub Issues**: [Mojaloop GitHub Issues](https://github.com/mojaloop/project/issues) +3. **Weekly community calls**: Join the weekly developer calls (details on the Mojaloop website) + +Happy developing with Mojaloop! \ No newline at end of file