Global

# Web services: general rules

{{>toc}}

## Some basic rules

* We will expect requests in `POST`, not `GET`. We will not design URLs to communicate request parameters.

* All JSON data structures will have member names in full lowercase. No mixed-case will be used.

## Web service request format

* Example

```

{

    "ver": 1,

    "uid": 1234,

    "data": {

	"goal_id": 23

    }

}

```

* @ver@ is the API version to be used

* @uid@ is user id. For some web service calls it will be optional. e.g. when user is just playing around and creating temporary portfolios, GBA engine won't need @uid@ field. 

* @data@ is request data object. sample request objects for each API have been provided in [[Apicalls|API calls wiki]]

In some cases (e.g. [[Goallist]]) a web service only requires @uid@ as input. In those cases value of data will be an empty object.

e.g.

```

{

    "ver": 1,

    "uid": 1234,

    "data": {}

}

```

## Web service response format

A common JSON data structure will be returned by the API for success or errors. 

For successes following JSON structure will be returned.

```

{

  "status": "success",

  "data": {

    /* Application-specific data payload goes here. */

  },

  "message": [] /* Or optional success message */

}

```

The value of @data@ for each API call is provided in the [[Apicalls|API calls documentation]]. For errors, the following JSON structure will be returned.

```

{

	"status": "error",

	"data": {},

	"message": [{

		"code": "code1",

		"msg": "message1"

	}, {

		"code": "code2",

		"msg": "message2"

	}]

}

```

Example errors returned.

```

{

	"status": "error",

	"data": {},

	"message": [{

		"code": "permission_denied",

		"msg": "No permission for the requested operation."

	}, {

		"code": "account_restricted",

		"msg": "The user account is disabled."

	}]

}

```

## Reporting errors by web services

Each error reported has two parts

* the error code

* the human readable error message

The code is always going to be one word, always in lower case, with letters, digits, and/or underscore characters.

The code is the real indicator of the type of error, and must be used by the client code. It may handle the error, it may retry the operation, it may branch into a different path in the code, it may select a message to show the end-user, _etc_, as needed. The error message supplied by the GBA web service is meant for the programmer of the client software to understand and debug the web service call.

In multi-lingual user interfaces, the error message must be indexed to the combination of (language, errcode). The responsibility of designing and selecting meaningful error messages in the correct language lies with the client software, not with GBA. The client software dev team must build error message tables in each supported language, indexed with the GBA error-code. The error message supplied by GBA will always be in English, and may not have appropriate wording to display directly to the end-user. Its audience is the programmer of the client software.

## ID formats

All IDs internally generated by GBA, e.g. goal-ID, scheme-investment-ID, temporary-portfolio-ID, ops-list-ID, _etc.,_ are all to be treated as opaque strings, _not_ as integers.

The GBA rules for ID syntax is:

* opaque, meaningless string

* between 1 and 50 octets long, variable length

* one word, _i.e._ no spaces or special characters in the word, only letters and digits

* case sensitive

* may start with a digit or a letter

* equality test possible, _i.e._ if two ID strings are identical as strings and refer to the objects of the same class, then they refer to the same instance

* guaranteed unique, _i.e._ if two object instances of the same class exist in GBA, they are guaranteed to have two separate ID strings

* ordering is meaningless, _i.e._ "greater than" or "less than" operation is meaningless

Note that this means that GBA may use integers as IDs, and all these rules will be fulfilled. But while representing them in JSON, the IDs will always be enclosed in double-quotes, even if they "look like" integers.

Examples of IDs:

* "a0ae48b16f90db8f3c542f44f8103701"

* "5"

* "750294852039"

Examples of strings which are not IDs:

* "a0ae48b16f90db8f3c542f4/f8103701" (there's a special character in it)

* 5 (a digit without quotes is not a string)

* "776,245,664" (commas are not permitted in IDs)

* "62.6" (the period is not permitted)

## Authentication

GBA does no authentication of users who use the service. The front-end(s) which connect to GBA must have their own mechanism for authentication. GBA works with trusted client services, _i.e._ it trusts all requests it receives and believes all information given. If it receives a user-ID in a request, it makes no attempt to verify that this user-ID is valid or that it exists, or that it is allowed to use the GBA services.

## API versions

Any web service (we will refer to it as "service" here) which is exposed to multiple clients (software systems which send web services requests to our service) will, over time, have to serve old clients and new ones.

Our service will grow in features and functionality, and the semantics of some web services may change. For instance, a particular web service may have been released initially with just three parameters in its input, but a fourth parameter was felt necessary after two years of service. Some older clients will still access the web service with three parameters and newer clients will pass four parameters to it. _C'est la vie_. One of the most obvious examples of this is when mobile apps access a web service. Some phones will have older releases of the mobile app and others will have newer releases. This makes it necessary for the web service to serve all generations of clients without breaking any.

One way to handle this is by adding an "API version number" parameter to each web service. This will be a mandatory parameter from Day 1. Initial clients will all be told to use @"ver": 1@ in their requests. When the service upgrades any web service and semantics change, then it will support the old semantics under @ver=1@ and newer semantics with @ver=2@. Newer clients which are aware of the updated semantics will use @ver=2@ in their requests. Older clients will not be aware of any changes.

The version number applies to each web service in isolation. The service as a whole may have versions 1 and 2 supported for some calls, 1, 2 and 3 for other calls, and just 1 for calls which have not changed at all.

This will go on, and new generations of web services will keep getting released. This will allow a single service to service multiple generations of clients at the same time.

This design approach is being used in GBA. The @ver@ parameter is mandatory and has an integer value.

## History tables

Transaction tables which receive updates will also have history tables which "shadow" the main tables. This will ensure that, taken in an overall database context, all updates are non-destructive, because all before-images of records can be reconstructed by analysing the history tables.

History tables will contain

* previous images of updated records

* deleted records

The following policies will be applied for maintenance of history information:

* When a record is inserted in a main table, nothing is done to the history table. (This means that there is no history-related overhead of compute power or disk space for tables which are not modified much.)

* When a record is updated in a main table, its previous image is first inserted into the history table and then the data is updated in the main table

* When a record is physically deleted (_i.e._ using the SQL @DELETE@ operation) from a main table, the to-be-deleted record is first copied into the history table

* When @truncate@ operation is performed on the table, all the rows in the current table will be inserted to its history table

These are the implementation specifications for implementing the history feature:

* All main tables which are supposed to get the benefit of history tracking will now have corresponding history tables to "shadow" them. If the main table is called *@X@*, its shadow table will be called *@X_hist@*.

* The history maintenance feature will be implemented using Postgres triggers.

* The shadow table will have identical schema to the main table, with two additional fields:

** *@hist_when@*: timestamp specifying when this record was inserted in the shadow table

** *@hist_op@*: will contain either "@U@", "@D@" or "@T@", indicating that this history replica is because of an u(pdate), d(eletion) or t(runcated)

* The GBA application code will connect to the database using a specific database username and password meant for business operation. (Let's say that this username is @gba@.) This username will not have any rights on the shadow tables other than @INSERT@ rights. A separate, second database user (let's say, @gbahist@) will have @SELECT@ rights on the shadow table, and only the administrator will be able to modify the contents of shadow tables.

## Timestamps

As per JSON Schema specification for "date-time":http://json-schema.org/latest/json-schema-validation.html#anchor108, for timestamps values, we will always use the format defined in "RFC 3339":https://tools.ietf.org/html/rfc3339#section-5.8 _e.g._ @1990-12-31T23:59:50Z@ for an Indian timezone timestamp or @201512-31T23:59:50+05:30@ for an Indian timezone timestamp.