Hello!

product installation

Installation Steps
==================

----------


Step 1. Downloading the webserver.
----------------------------------

We use WAMP Server as our primary web server software to run our Portal on our local system. You can download the same from http://www.wampserver.com/en/. If you are running a 32-bit Windows system make sure you choose the correct setup package.

Once the download is complete, make sure you run the setup file as an administrator (Right click on setup file > **Run as administrator**).

Once the installation is done you can run the WAMP server from the Program menu.

> NOTE: If you have Skype installed, make sure it's not running at the moment. If its running, exit Skype since it also uses port 80 and 443 for incoming connections. You can safely run Skype after running WAMP server.

Select PHP version 7 in your WAMP server by left clicking on the WAMP icon in your system tray and then **PHP** > **Version** > **7.x.x** > **Restart All Services**


Step 2. Installing the PHP extensions
-------------------------------------

Since we are using MSSQL server as our database, it's important to install the appropriate extensions to make our laravel application talk to the MSSQL database server.  The two php extensions that you would need are

**For 32-bit machines**
*php_sqlsrv_7_ts_x86.dll*
*php_pdo_sqlsrv_7_ts_x86.dll*

**For 64-bit machines**
*php_sqlsrv_7_ts_x64.dll*
*php_pdo_sqlsrv_7_ts_x64.dll*

These are available for download from our Github repository, under ***TriCoreSolutions\api\php_extensions***

Once downloaded, please copy the extensions and paste it under the following directory ***C:\wamp64\bin\php\php7.0.10\ext***
(assuming you have installed WAMP in its default path)

To activate these extensions in PHP, open the php.ini file by Left clicking on WAMP icon on your system tray then go to **PHP** > **php.ini** then scroll down to the **Windows Extensions** section and paste the following lines

> extension=php_sqlsrv_7_ts_x##.dll
extension=php_pdo_sqlsrv_7_ts_x##.dll

where **##** can either be **86** or **64** depending on your machine type.

Step 3. Cloning the API repository
----------------------------------

Assuming you already have a Github account (create one if you do not), Go to https://github.com/TriCoreSolutions/api and click on the **Fork** button on the top right corner. Once you have forked the API repository into your own account you can now clone it on your local server. Once cloning is done, you should run composer install to download all the dependent files. Please follow the steps as described below

>  ~ cd  c:\wamp64\www
 ~ mkdir TriCoreSolutions
~ cd TriCoreSolutions
~ git clone git@github.com:{your username here}/api.git
~ cd api
~ composer install

Add a remote in git pointing to the original repo from where you will fetch/pull the latest changes. So run the following command to add a remote and name it **upstream**

>  git remote add upstream git@github.com:TriCoreSolutions/api.git

This means that you should always push your changes to **origin** (i.e your own repo) and pull latest changes from **upstream**. To merge changes to **upstream**, you should create a pull request from your repo to the main repo of **TriCoreSolutions**.

Step 4. Creating a Virtual Host
-------------------------------

The next step is to create a virtual host in your WAMP server. Creating a virtual host will allow you to have a customized url for your application. Steps to create a virtual host are given below:

- Open any browser and navigate to http://localhost (make sure your WAMP server is working and the icon in the system tray is GREEN). You will see the default configuration page of WAMP.

- Go to **Tools** > **Add a Virtual Host**

- Under **Name of the Virtual Host**, specify **api.tricore.app**

- Under **If you want to use VirtualHost by IP**, leave the field empty

- Under **Complete absolute path of the VirtualHost folder**, specify **c:/wamp64/www/tricoresolutions/api/laravel/public**

- Click the button **Start the creation of the VirtualHost**

- Once added successfully, you should see a message that reads **The files have been modified. Virtual host test was created**

- The next step is restarting the DNS. Do this by Right clicking on the WAMP server icon in your system tray and then go to **Tools** > **Restart DNS**

- The final step is to shutdown WAMP by right clicking on WAMP icon in your system tray and then select **Exit**, This will force WAMP to reload all configurations and settings that we added/modified earlier. Start the WAMP server again from the program menu.

Step 5. Testing your web app
----------------------------

Now that you are all set with your installations and configurations, its time to test whether your web app is working or not.

Fire up your favorite browser and resolve the url http://api.tricore.app/docs/routes

This should display the API documentation of the portal. To test the APIs you can use a third-party REST client like Postman (download from https://www.getpostman.com/).

Next we will check if our app is serving the request from the database which is connected to a remote server. Make sure you are connected to the VPN (otherwise your API request will not work)

Open Postman and make a POST request to http://api.tricore.app/auth?email=dnewby&password=secret1

If everything is running properly, it will return a JSON Web Token (JWT) as shown in the image below.

![jwt response](http://i.imgur.com/nOQRf0R.png)

Copy the token value and make a GET request to http://api.tricore.app/organizations along with an **Authorization** header containing the value **Bearer** followed by the token as shown in the image below

![enter image description here](http://i.imgur.com/h5noQkD.png)


## What next?
Go through the API documentations at http://api.tricore.app/docs/routes and try out other APIs listed there.

### Users for testing

> Email: dnewby@tricoresolutions.com
Password: secret
Role: Portal Admin

> Email: ehackett@tricoresolutions.com
Password: secret
Role: Portal Basic

> Email: aconklin@tricoresolutions.com
Password: secret
Role: Customer Basic

## Includes

Includes are an additional parameter that you can pass for certain routes that will included related data. An example would be on the users route:

`/users?include=roles&token=your_token`

Includes through can be used to include data that is related to the include. For example if you want to see the permissions associated with each role that is related to the user:

`/users?include=roles.permissions&your_token`


## Authentication

The token that is returned is required for all API calls other than Get Token.

### Get token.

**POST** `/authenticate`

Example

`/authenticate?email=your_email&password=your_password`

Required

`email`

`password`

Returns

`token`


### Check if authenticated.

**GET** `/authenticate/user`

Returns `1` or `0`.


## Tickets

### All

**GET** `/ticket`

_paginated_

### Individual

**GET** `/ticket/$id`

## Organizations

### All

**GET** `/organization`

_paginated_

### Individual

**GET** `/organization/$id`

## Users

### All

**GET** `/user`

###### Includes

`roles`

`roles.permissions`

_paginated_

### Individual

**GET** `/user/$id`


## HTTP Status Codes Reference

These will most likely change.

- **200** Generic everything is OK.
- **201** Created something OK.
- **202** Accepted but is being processed async (for a video means encoding, for an image means resizing, etc.)
- **400** Bad Request (should really be for invalid syntax, but some folks use for validation).
- **401** Unauthorized (no current user and there should be).
- **403** The current user is forbidden from accessing this data.
- **404** That URL is not a valid route, or the item resource does not exist.
- **405** Method Not Allowed (your framework will probably do this for you).
- **410** Data has been deleted, deactivated, suspended, etc.
- **500** Something unexpected happened, and it is the APIs fault.
- **503** API is not here right now, please try again later.