NAV Navbar
Logo
code

Introduction

Welcome to the minewave API! The API service is exposed via HTTP/2.

All clients MUST ALWAYS use the API service in a SINGLE BACKGROUND THREAD to synchronize server resources with local database.

All UI should be bind to the synchronized database, interact with the BACKGROUND THREAD whenever API requests are needed.

If ALWAYS or MUST present, that means exactly you MUST ALWAYS conform to it.

Request

HTTP Headers

To access the API with curl, use this code:

curl "https://api.minewave.in"
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: 176e57249a56eb0f75520e5939d3bc0b"

Make sure to use correct X-Minewave-API-Token and X-Minewave-User-Token.

The API requires four headers to work.

key value
Content-Type application/json
Accept application/vnd.minewave.in+json; version=1
X-Minewave-API-Token d89e69055e5f1e1015bcc315c2e46d75
X-Minewave-User-Token 176e57249a56eb0f75520e5939d3bc0b

HTTP Methods

The API only accepts GET and POST requests.

The endpoints should usually take POST when the client needs to modify something on the server, and GET when the client only needs to fetch some data from the server.

You should refer specific endpoints documentation.

Request Body

Request body MUST be a valid JSON format.

You MUST use the POST HTTP method when a request body is presented.

Response

HTTP Status Codes

if (status_code == 200) {
  deal_with(response_body);
} else if (status_code >= 500 && status_code < 600) {
  do_nothing_with(response_body);
  notify_user("there are some server errors");
} else {
  // MUST communicate with the server developers to fix the bug
}

The API service try to treat HTTP/2 as a transfer protocol and only use the status code 5XX and 200.

  1. 5XX means some server errors occur. The client SHOULD notify the user and do nothing else.
  2. 200 means the API has successfully processed the request. The client SHOULD parse the response body to continue.
  3. Any other status codes means server bug, MUST contact the server developers to fix it.

Response Body

Below is a full response object representation. NOT all fields will be included in a real API response.

{
  "data": [{
    "type": "user",
     "id": "5392a05e30786145d60b0000"
  }],
  "prev": "/conversations?offset=timestamp&limit=100",
  "next": "/conversations?offset=timestamp&limit=100",
  "error": {
    "code": 100500,
    "description": "the client should localize this description in app"
  }
}

The data field MAY contain an array or object.

if (response_body->error != NULL) {
  do_nothing_with(anything_else);
  deal_with_the(error);
} else {
  success();
}

The response is ALWAYS in a valid JSON format.

The response MAY include one of data or error field.

The response MAY include prev or next field.

Whenever an error field appears in the response, the client SHOULD deal with it and MUST NOT parse any other fields.

The data field MAY contain an array or object.

The prev and next field represents the API endpoint to GET corresponding resources.

The response MAY be an empty JSON {}.

Errors

The error codes are ALWAYS five digits, the first digit is the same as the API version.

You may find the code similar to some regular HTTP status codes.

Error Code Meaning
10400 The request body can’t be pasred as a valid JSON
10401 Missing or invalid X-Minewave-API-Token header
10402 Missing or invalid X-Minewave-User-Token header
10403 The X-Minewave-User-Token doesn’t have the right to access this endpoint
10404 The endpoint is not defined, or invalid methods, missing HTTP headers
10429 Too many requests, wait and slow down
10500 The API server has some error can’t be described

Verifications

Send SMS phone verification code and verify the code

Send Code

curl https://api.minewave.in/verifications
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -X POST -d '{"phone":"+8618621110407"}'

The above command returns JSON structured like this:

{
  "data": {
    "type": "verification",
    "id": "5848ea42f3d8bf0b26c4d59a",
    "is_new": true,
    "is_verified": false
  }
}

Return an error when the phone invalid.

Return the verification id, which can be used to verify the phone once received the SMS code.

HTTP Request

POST https://api.minewave.in/verifications

JSON Parameters

Parameter Description
phone Phone number in E.164 format

Verify Phone

curl https://api.minewave.in/verifications/5848ea42f3d8bf0b26c4d59a
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -X POST -d '{"code":"3149"}'

The above command returns JSON structured like this:

{
  "data": {
    "type": "verification",
    "id": "5848ea42f3d8bf0b26c4d59a",
    "is_new": true,
    "is_verified": true
  }
}

Return an error when the verification id or code invalid.

Return a verification object with is_verified: true if this is a new phone.

Return a user object if this is an old phone.

HTTP Request

POST https://api.minewave.in/verifications/<ID>

URL Parameters

Parameter Description
ID The verification ID generated in Send Code API

JSON Parameters

Parameter Description
code 4 digits verification code received in SMS

Accounts

Create Account

curl https://api.minewave.in/accounts
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -X POST -d '{"verification_id": "5848ea42f3d8bf0b26c4d59a", "full_name": "cedric", "avatar_base64": ""}'

The above command returns JSON structured like this:

{
  "data": {
    "type": "user",
    "id": "5848f8022a5194574f043077",
    "full_name": "cedric",
    "authentication_token": "dd0721db181b478b941bfca5535c2ce5",
    "avatar_url": "https://....",
    "phone": "+8618621110407"
  }
}

Return an error when the verification_id or username invalid.

Return a user object with authentication_token for further API calls.

HTTP Request

POST https://api.minewave.in/accounts

JSON Parameters

Parameter Description
verification_id The verification ID generated in Send Code API
username Only letters, numbers and _, length 2-32

Update Account

curl https://api.minewave.in/accounts/5848f8022a5194574f043077
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"
  -X POST -d '{"full_name": "new_name", "avatar_base64": "#####"}'

The above command returns JSON structured like this:

{
  "data": {
    "type": "user",
    "id": "5848f8022a5194574f043077",
    "full_name": "new_name",
    "avatar_url": "https://url",
    "authentication_token": "dd0721db181b478b941bfca5535c2ce5",
    "phone": "+8618621110407"
  }
}

HTTP Request

We now recommend the client only post required parameters to API service if possible.

E.G. you may omit the username field if you only want to update the avatar_base64

POST https://api.minewave.in/accounts/<ID>

URL Parameters

Parameter Description
ID The user id

JSON Parameters

Parameter Description
username Optional
avatar_base64 Optional

Friends

My Friends

curl https://api.minewave.in/friends
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"

The response data is an array of users

{
  "data": [{
    "type": "user",
    "id": "5848f8022a5194574f043077",
    "username": "new_name",
    "avatar_url": "https://url"
  }]
}

A friend is somebody I’m following, no matter I’m followed back or not.

HTTP Request

GET https://api.minewave.in/friends

Friends Requests

curl https://api.minewave.in/friends/requests
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"

The response data is an array of users

{
  "data": [{
    "type": "user",
    "id": "5848f8022a5194574f043077",
    "username": "new_name",
    "avatar_url": "https://url"
  }]
}

A friend request is somebody who follows me but I’m not following him.

HTTP Request

GET https://api.minewave.in/friends/requests

Contacts

Upload Contacts

curl https://api.minewave.in/contacts
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"
  -X POST -d '[{"phone": "+8618621110407", "full_name": "Cedric Fung"}]'

Upload the full contacts list. The client MUST include all contacts whenever this API is called.

The phone field MUST be a valid E.164 format, MAY use the libphonenumber to help.

Return an error or blank object {}.

HTTP Request

POST https://api.minewave.in/contacts

JSON Parameters

Parameter Description
phone Phone number in E.164 format
full_name The name in the phone contacts list

Joined Contacts

curl https://api.minewave.in/contacts/in
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"

the response is a contacts list with minewave user_id

{
  "data": [
    {
      "type": "contact",
      "user_id": "5848f8022a5194574f043077",
      "phone": "+8618621110407",
      "full_name": "Cedric Fung"
    }
  ]
}

This API represents the contacts that have joined minewave, but I haven’t followed yet.

HTTP Request

GET https://api.minewave.in/contacts/in

Not Joined Contacts

curl https://api.minewave.in/contacts/out
  -H "Content-Type: application/json"
  -H "Accept: application/vnd.minewave.in+json; version=1"
  -H "X-Minewave-API-Token: d89e69055e5f1e1015bcc315c2e46d75"
  -H "X-Minewave-User-Token: dd0721db181b478b941bfca5535c2ce5"

the response is a contacts list without minewave user_id

{
  "data": [
    {
      "type": "contact",
      "phone": "+8618621110407",
      "full_name": "Cedric Fung"
    }
  ]
}

This API represents the contacts that have not joined minewave yet.

HTTP Request

GET https://api.minewave.in/contacts/out