Working with Contacts

Each globaliD identity has its own list of contacts. A contact is simply another identity that this user has decided is important in some way. An obvious use of contacts is to make it easier to send a message to someone: you add someone to your contact list and can then simply tap on them to send them a message.

The list of contacts for an identity is private -- that is, nobody other than the identity themselves can view the identity's contact list. However, there is one important caveat to this, which is the notion of a mutual contact. Several features within globaliD, including messaging, impose a charge or other restriction if you attempt to interact with someone who does not have you in their contact list. To be able to tell which other identities have you on their contact list, the system implements the notion of a "mutual" contact. A contact is mutual if and only if both identities have each other in their respective contact lists. Both identities can see if the contact is mutual or not.

Retrieving the List of Contacts

To retrieve the list of contacts for an identity, you can call the GET /v1/contacts API endpoint. For example:

Request:

    GET /v1/contacts
      BEARER <access_token>

Response:

    HTTP/1.1 200 OK

    {
      "data": [
        {
          "contact_uuid": "...",
          "gid_uuid": "...",
          "mutual": true
        },
        ...
      ],
      "meta": {
        "page": 1,
        "per_page": 50,
        "total": 72
      }
    }

As you can see, this endpoint requires you to supply an access token linked to the identity you wish to retrieve the contacts for. Upon completion, an array of contacts is returned in the data field. For each contact, three pieces of information will be returned:

* __contact_uuid__: the gid_uuid of the contact [CHECK].
* __gid_uuid__: the gid_uuid of the owner of this contact list [CHECK].
* __mutual__: a boolean indicating whether or not the contact is mutual.

The meta object returns information on the pagination of the contact list:

*   __page__: the page number of the results, where the first page number is 1.
* __per_page__: the number of contacts in each page of results.
* __total__: the total number of contacts in the contact list.

To download all the contacts, start by calling this API endpoint to load the first page of contacts. You can then use the information in the meta object to see how many pages of results you need to download. You can then download additional pages of results to get all the contacts. For example:

`GET /v1/contacts`
`GET /v1/contacts?page=2`
`GET /v1/contacts?page=3`
...etc

You can also use the per_page parameter to control how many contacts to return in each page of results.

Adding a new Contact

To add a new contact, simply call the POST /v1/contacts endpoint with the following details:

Request:

   POST /v1/contacts
   BEARER <access_token>

   <contact's gid_uuid>

Response:

   HTTP/1.1 201 Accepted

   {
     "contact_uuid": "...",
     "gid_uuid": "...",
     "mutual": true
   }

As you can see, the API endpoint returns the newly-generated contact.

Removing a Contact

To remove an existing contact, call the DELETE /v1/contacts/:gid_uuid endpoint, where gid_uuid is the UUID of the contact to remove.

Request:

   DELETE /v1/contacts/<gid_uuid>
   BEARER <access_token>

Response:

   HTTP/1.1 204 No Content

Retrieving a Specific Contact

To retrieve the details for a single contact, you can call the GET /v1/contacts endpoint with an additional query-string parameter, like this:

`GET /v1/contacts?contact_gid_uuid=<contact's gid_uuid>`

The API endpoint will return the contact for the given gid_uuid, if this identity is in the caller's contact list:

    {
      "data": [
        {
          "contact_uuid": "...",
          "gid_uuid": "...",
          "mutual": true
        }
      ],
      "meta": {
        "page": 1,
        "per_page": 50,
        "total": 72
      }
    }

If the given gid_uuid is not listed in the calling identity's contact list, then the data field will be empty:

    {
      "data": [],
      "meta": {
        "page": 1,
        "per_page": 50,
        "total": 72
      }
    }