API enhancement

API enhancement

Byblos API enhancements
=======================

## Version
The version of the API should be included in the base URL of the API precedeed with the letter v
e.g. `//myapi.com/v1/accounts`

## Naming
### Use names for resources and verbs for actions
Provide sensible **names** for the applications resources	
		
    /accounts (instead of GetAccountListDetailsRequest)
	/loans
	/cards
	/products (instead of GetProductsListDetailsRequest)

Use **verbs** for responses that don't involve resources

Api calls that send a response that's not a resource are not uncommon depending on the domain, actions like the following are your clue that might not be dealing with a "resource" response

 - Convert currencies 	
      
         GET /convert?from=USD&to=LBP&amount=10
   
 - Check SOD status
               
        GET /sod
   
 - Perform a transfer
       
        POST /transfer (instead of InputTransferRequest)
 - Authentication
        
        POST /auth/login
        POST /auth/logout
     
      
Use HTTP verbs to apply CRUD operations
    
  - list all the accounts for the authenticated user

	    GET 	/accounts
	
  - submit a loan payment
    
        POST 	/loans/7894/payments 

  - submit a feedback

	    POST 	/feedback

## Response Type
The responses should return the response in a valid `JSON` format
JSON can be easily read through JavaScript, which eliminate the expensive processing needed for transforming from/to `XML` on the device for each request

## Status Code
The responses should return a relevant HTTP status code 

	200	Successful
	400 Bad request
	401 Not authorized
	403 Forbidden
	404 Not found
	500 Internal server error
	503 Service unavailable

## Response fields
The response should only returns the required fields by the application, additional fields lead to:

   - Additional processing from the mobile
   - More time to download
   - Provide additional information for Hackers 
   - Confuse the developers using the API

## Business logic
All the business logic should be treated on the server, no processing should be made on the mobile App.
  
  - Separation of joint/private accounts (same for cards and loans)
  - Extracting related cif for the user
  - Get the status of the login operation with codes
      - is new device
      - user locked
      - need to reset the password
      - ...
  - Checking accounts status for transfer (same for loans and cards)
  - Same request to fetch the account transactions for different account types

## Authentication and Sessions
Private requests should be authenticated via username and password, the session of the logged in user should be stored in the server, once the authentication success the server send the session token for the client.

 - The session token is the **only required** parameter needed to identify the logged in user
 - The session token can be sent either in the HTTP request header or in the body as additional parameter. (We recommend the header)
 - When the client request the accounts for example, the server should automatically return the accounts related for the logged in user, with no need to specify this explicitly.
 - Unauthorized requests should return the HTTP status code 401
 - The session will be  destroyed automatically after X minutes

 
## Avoid Successive Requests
In some situations where successive requests needed, i.e. In the loan payment, it's recommended to combine them as much as possible to reduce the connection needed between the mobile app and the server

  - Request to **Check the SOD flag**
  - Another request to **Submit the payment**

Should be: 
  
- One request to submit the payment, and return a flag if the SOD flag is enabled.

## API consistency
The requests and responses should be consistent on how the data is sent to the server (param names, urls, etc...) and how the data is returned.

 - The card transactions response should be similar to the account transactions
 - The same for loans transactions
 - use a well defined terminology for fields name, i.e. `balance` for the account balance, `availableBalance` for the available balance for transfer, and avoid miss leading attributes i.e. `transferBalance`, `transferAvailableBalance`, `workingBalance`, `transAvailableBalance`

## Attributes Names
Response attributes name should be provided in a consistent format, 

 - We recommend the `camelCase` notation
 - Do not append the resource name in the field

```javascript
{
    "id": 9087,
    "category": "Saving",
    "customerName": "Fadi Nassar",
    "longAttributeName": "this is the value"
}
```
Examples of *invalid* format

```javascript
{
    "accountCustomerName": "Jad choueiri", // appending the resource name
    "CustomerName": "...", // should be in camel case format
}
```

## Attributes data types
The attributes data types should return the correct data type according to each field

  - use boolean `true` and boolean `false` for boolean values

```javascript
    {
        // valid values
        "canTransfer": true, // ✓
        "isAvailable": false, // ✓
        
        // invalid values
        "canTransfer": "true", // ✘
        "canTransfer": 1, // ✘
        "isAvailable": 0, // ✘
        "isAvailable": null, // ✘
    }
```

- use numbers values for `Integers` and `Real` numbers 

```javascript
    {
        "availableBalance": 300.5, // ✓
        "availableBalance": "300.5", // ✘
    }
```

## Response encoding
All the data returned by the response should be automatically encoded

```javascript
    {
        "description": "<div>content inside a div >/div<", // ✓
        "description": "<div>content inside div</div>", // ✘
    }
```

## Documentation
All the request have to be well documented and describing the parameters needed with examples and the expected responses.

i.e. Get user accounts `/accounts`

|param|required|default|note|
|------|-------|-----|----|
| type | false | `all` | one of `private`, `joint` or `all` |
| canTransferOut | false | `null` | one of `true` or `false`


**Request**
    
    GET /accounts
    X-Session-Token a3ger785Yxzd
    
**Response 1**

    HTTP/1.1 200 OK
    [{
        "id": 789654,
        "isJoint": false,
        "jointCustomerId": 651001,
        "name": "Jana Hamoud and Alaa Fakih",
        "balance": 325000,
        "transferBalance": 700000,
        "currencyCode": 1 
    }]

**Response 2**

    HTTP/1.1 401 Not Authorized
    {
        "error": "Plain message goes here"
    }

**Response 3**

    HTTP/1.1 400 bad request
    {
        "error": "Missing required parameter X"
    }

**Response 4**

    HTTP/1.1 503 OK
    {
        "error": "The server is down, please try again later"
    }