Biblical Resources for Translators API

Laravel

The API is built in Laravel, a PHP framework. To get the backend up and running locally Laravel Homestead is the recommended approach. Laravel is currently on version 8, but our system is using the version 7.x series. Just make sure you grab the correct version to avoid any possible snags that could show up across major versions.

Homestead uses Vagrant which is a virtual machine tool to make building and maintaining VMs easier. By using a VM to host the API server, we can avoid potential conflicts with the local development environment of our respective host machines. The files under development are stored in local folders on the host machine which are mapped to folders on the guest VM. The documentation on Vagrant and Homestead are quite helpful.

If Homestead is not an option, you may follow the installation directions in the Laravel documentation to install Laravel directly on your local machine and run php artisan serve. You will need to alter the Frontend's environment configuration to point to the correct server.

Config Homestead Project

Once Laravel Homestead is installed and working, you will need to setup a project in the Homestead.yaml file. This process requires that you determine a local hostname to use for the API server and a suitable location for the code. A typical setup would use brt.api or brt.local as the hostname. The folder/directory can be anywhere your user account has read/write permisisons but typically will be something like ~/Code/brt. With these values in mind, you would edit your Homestead.yaml file and add the following:

folders: 
    - map: ~/Code/brt/
      to: /home/vagrant/brt

sites:
    - map: brt.api
      to: /home/vagrant/Code/gwt/public
      php: "7.2"

databases:
    - brt

A complete Homestead.yaml file might look like the following (keep in mind that if you use Homestead for other projects your Homestead.yaml file will look very different, but then you would probably already know that and not need this document ;-) )

---
ip: "192.168.1.80"
memory: 2048
cpus: 2
provider: virtualbox

authorize: ~/.ssh/id_rsa_key.pub

keys:
    - ~/.ssh/id_rsa_key

folders:
    - map: ~/Code/brt/
      to: /home/vagrant/code

sites:
    - map: brt.api
      to: /home/vagrant/Code/gwt/public
      php: "7.2"

databases:
    - brt

variables:
    - key: APP_ENV
      value: local

ports:
    - send: 9912
      to: 9912

The folders block configures a fileshare connection between the vagrant box and your local filesystem. The map variable is the location of your project code from the perspective of your host machine. It is where you will point your code editor while you work on the project. The to variable is where the virtual machine (VM) looks for that same code. It is not aware of the filesystem layout of your host machine, so it needs to know how to find your code from within its own environment. Think of it as a roadmap where the street names are different depending on whether you are a local or a guest.

The sites block works similarly, only now we are telling Vagrant how to configure the web server that will serve up our API. map is the hostname we will use in the browser (though in our case we are not accessing the backend API via a browser. Try it, you won't get very far. This is because the actual frontend (FE) for the site lives in a different repo). to refers to the place where the web server will need to find the startup code for the site. Note that it is not exactly the same as what we have set in the folders block. This is important because the public subfolder of a Laravel project contains an index.php file which is what 'boots' the system whenever the API is accessed by the web server.

If you are unsure where your Homestead.yaml file is or need help configuring additional options re-visit the section above.

Backend Code (This Repo)

Once your VM is configured, you need to clone this repo (en_btr_backend) into your local working directory so that your VM can read the code. Do this by running the following command within a terminal window within your local working directory:

git clone https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_backend.git .

Not the space + period at the command. Don't leave it out. Otherwise, git will create a new folder named en_btr_backend and you will need to update your Homestead.yaml file or delete the new folder and try again. Either approach is fine, just don't be fooled by git's strong opinions.

Once you have cloned the backend code, go ahead and try running vagrant up in your ~/Homestead folder. If your Homestead.yaml configs are in good order Vagrant should take off and start dumping a lot of information to your terminal screen. Don't worry about it unless (or until) Vagrant complains with an error. If you hit an error, revisit the above steps and verify your configuration. If you still have issues and you cannot get past the vagrant up process, you will need some extra assistance. Let us know, and we will do our best to help you.

Build the database

Assuming that Vagrant succeeded, you now have fully functional VM ready to run the API on your computer. That's great! But you still need some data or the API is useless. The source data for the project lives in various repos at WA's git server, but you don't need to worry about that. For testing purposes, there are some files provided in this repo under the test_files folder. You will need to move them to the storage folder so that the Laravel app can find them and use them to build the DB. Run the following command from within your local working directory:

cp -fr test_files/* storage/

Now the files we need are located within the storage folder which is where they will ultimately be housed on the live API server. With the test files in place, you are almost ready to build the database. However, before you can build the database, you need to make sure that your Laravel config knows how to access the database. Open up the .env file in your editor (the .env file is in the root of the project folder). Make sure these settings are somehwere in that file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=gwt
DB_USERNAME=homestead
DB_PASSWORD=secret

Now (as in right now, don't wait!), run the following command:

php artisan gwt:import-lexical-entries

and

php artisan gwt:import-ulb-xml

These two commands don't give you much output unless something breaks. When they are completed, your database will have the data to run the API server on your local machine.

THAT'S A WRAP!

At this point, there is not much else you can do with the API. It serves up the files needed by the frontend so that the frontend can build the site in a browser. If you want to prove that the API exists and works, you can run the following command in your terminal:

curl http://gwt.api/api/v1/books

You should get something back that looks like

{"data":[{"type":"books","id":"colossians","attributes":{"name":"Colossians","created-at":"2020-10-07T15:28:35+00:00","updated-at":"2020-10-07T15:28:35+00:00"},"relationships":{"chapters":{"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/colossians\/relationships\/chapters","related":"http:\/\/gwt.api\/api\/v1\/books\/colossians\/chapters"}}},"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/colossians"}},{"type":"books","id":"philippians","attributes":{"name":"Philippians","created-at":"2020-10-07T15:28:07+00:00","updated-at":"2020-10-07T15:28:07+00:00"},"relationships":{"chapters":{"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/philippians\/relationships\/chapters","related":"http:\/\/gwt.api\/api\/v1\/books\/philippians\/chapters"}}},"links":{"self":"http:\/\/gwt.api\/api\/v1\/books\/philippians"}}]}

Yes, it looks like "YUCK! I can't do anything with that." But don't worry. The frontend loves this stuff and will have no trouble eating it up, I mean, consuming it ;-).

To get the frontened up and running, head on over to https://content.bibletranslationtools.org/WycliffeAssociates/en_btr_frontend