commodity dollar

Z+ API

Server-side API phục vụ backend logic cho hệ sinh thái Z+

Lưu ý:

  • những API có mặt trong văn bản này đủ để phục vụ các tính năng thiết yếu nhất theo yêu cầu của hệ sinh thái Z+, tuy nhiên đây chÆ°a phải là danh sách đầy đủ nhất, và các nhóm phát triển có thể đề xuất nếu cảm thấy phù hợp hoặc cần thiết.

  • các cấu trúc, tên biến, tên header, v.v… trong văn bản này mang tính chất tham khảo, các nhóm phát triển có thể thay đổi tùy tình huống thá»±c tế, nếu có nhu cầu.

  • các đầu cuối trong văn bản này không nhất thiết phải thuộc cùng 1 service hay server vật lý, mà có thể được rải ra các services khác nhau, tùy theo ý đồ kiến trúc hệ thống của các nhóm phát triển.

Một số khái niệm:

Tên Ý nghĩa
public-facing API đầu cuối này được thiết kể để gọi trực tiếp từ client (ví dụ: iOS app). Nếu cần giới hạn quyền truy cập, có thể thông qua header token hoặc cookie.
private-facing API đầu cuối này được thiết kế để gọi trực tiếp từ server (ví dụ: server của DPM). Nếu cần giới hạn quyền truy cập, có thể thông qua header token hoặc cookie, kèm theo API KEY được bí mật lưu hành giữa 2 servers.

SSO - VIVAS

Đăng nhập

Đăng nhập
POST/sso/login

Phương thức gọi: public-facing API

Example URI

POST /sso/login
Request
HideShow
Body
{
  username: "the login ID", / ví dụ: SĐT của người dùng
  password: "the login password"
}
Response  200
HideShow
Headers
Content-Type: application/json
Set-Cookie: sso_token=xyz
Body
{
  sso_token: "xyz",
  userID: "1",
  full_name: "Bờm",
  ...
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Thông tin đăng nhập không đúng"
}

Đăng xuất

Đăng xuất
GET/sso/logout

Phương thức gọi: public-facing API

Example URI

GET /sso/logout
Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200

Xuất thông tin tài khoản người dùng

Xuất thông tin tài khoản người dùng
GET/sso/user/{sso_token}

Phương thức gọi: public-facing API

Example URI

GET /sso/user/xyz
URI Parameters
HideShow
sso_token
string (required) Example: xyz

giá trị token trả về từ /login

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  userID: "1",
  full_name: "Bờm",
  ...
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng không tồn tại, hoặc chưa đăng nhập"
}

Đăng ký mới tài khoản

Đăng ký mới tài khoản
POST/trusted/user/registration

Phương thức gọi: private-facing API

Example URI

POST /trusted/user/registration
Request
HideShow
Headers
X-DPM-API-KEY: SECRET_BETWEEN_VIVAS_AND_DPM
Body
{
  phone: "0900000000",
  full_name: "Bờm",
  ...
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  userID: "1",
  verified: true
  ...
}

VOD & Stream

Xuất danh sách video clip

Xuất danh sách video clip
GET/vod-items{?category,size,from}

Phương thức gọi: public-facing API

Example URI

GET /vod-items?category=dia_ly&size=50&from=0
URI Parameters
HideShow
category
string (optional) Example: dia_ly

tiêu chí lọc; nếu để trống, xem như không lọc (trả về tất cả)

size
number (optional) Example: 50

số lượng bản ghi trả về

from
number (optional) Example: 0

thứ tự bản ghi trả về

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "abc",
    "title": "Cà Chua và Canh Trứng",
    "hls_url": "/cdn.vivas.tld/abc.m3u8",
    "ad_endpoint": "/ad.vivas.tld/abc.m3u8",
    "...": "..."
  }
]
Schema
{
  "$schema": "/json-schema.org/draft-04/schema#",
  "type": "array"
}

Xuất thông tin của 1 video clip

Xuất thông tin của 1 video clip
9712208944/vod-item/{vodID}

Phương thức gọi: public-facing API

Example URI

GET /vod-item/abc
URI Parameters
HideShow
vodID
string (required) Example: abc

ID của video clips

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "abc",
  "title": "Cà Chua và Canh Trứng",
  "hls_url": "/cdn.vivas.tld/abc.m3u8",
  "ad_endpoint": "/ad.vivas.tld/abc.m3u8",
  "...": "..."
}
Schema
{
  "$schema": "/json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "hls_url": {
      "type": "string"
    },
    "ad_endpoint": {
      "type": "string",
      "description": "đầu cuối trả về nội dung quảng cáo cần tiêu thụ trước khi truy cập được nội dung video hiện tại"
    },
    "...": {
      "type": "string",
      "description": "Các thông tin liên quan khác"
    }
  },
  "required": [
    "id",
    "title",
    "hls_url"
  ]
}

Yêu cầu nội dung HLS

Yêu cầu nội dung HLS
318-934-7646/hls/{vodID}.m3u8

Phương thức gọi: public-facing API

Example URI

GET /hls/abc.m3u8
URI Parameters
HideShow
vodID
string (required) Example: abc

ID của video clip

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200
HideShow
Headers
Content-Type: application/x-mpegURL
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng chưa đăng nhập"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng không là thành viên đăng ký tháng, hoặc không đủ xu trong tài khoản"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng chưa xem nội dung quảng cáo tương ứng"
}

Games - 3rd-party

Xuất danh sách trò chơi có trên hệ thống

Xuất danh sách trò chơi có trên hệ thống
5156978797/games

Phương thức gọi: public-facing API

Example URI

GET /games
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "duoi_hinh_bat_chu",
    "title": "Đuổi hình bắt chữ",
    "ad_endpoint: /ad.vivas.tld/duoi_hinh_bat_chu": "Hello, world!",
    "...": "..."
  }
]
Schema
{
  "$schema": "/json-schema.org/draft-04/schema#",
  "type": "array"
}

Xuất thông tin chi tiết của 1 trò chơi

Xuất thông tin chi tiết của 1 trò chơi
620-518-4523/game/{gameID}

Phương thức gọi: public-facing API

Example URI

GET /game/duoi_hinh_bat_chu
URI Parameters
HideShow
gameID
string (required) Example: duoi_hinh_bat_chu

ID của trò chơi

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "duoi_hinh_bat_chu",
  "title": "Đuổi hình bắt chữ",
  "ad_endpoint: /ad.vivas.tld/duoi_hinh_bat_chu": "Hello, world!",
  "...": "..."
}
Schema
{
  "$schema": "/json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "ad_endpoint: /ad.vivas.tld/duoi_hinh_bat_chu": {
      "type": "string",
      "description": "đầu cuối trả về nội dung quảng cáo cần tiêu thụ trước khi truy cập được nội dung game hiện tại"
    },
    "...": {
      "type": "string",
      "description": "Các thông tin liên quan khác"
    }
  },
  "required": [
    "id",
    "title"
  ]
}

Cập nhật kết quả sau khi chơi

Cập nhật kết quả sau khi chơi
POST/game/{gameID}/{sso_token}

Phương thức gọi: public-facing API

Example URI

POST /game/duoi_hinh_bat_chu/xyz
URI Parameters
HideShow
gameID
string (required) Example: duoi_hinh_bat_chu

ID của trò chơi

sso_token
string (required) Example: xyz

token đăng nhập trả về từ /sso/login

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Body
{
  score: 95
}
Response  200
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng chưa đăng nhập"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng không là thành viên đăng ký tháng, hoặc không đủ xu trong tài khoản"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  message: "Người dùng chưa xem nội dung quảng cáo tương ứng"
}

Games - Islands

Lấy nội dung hiện tại cho kiến trúc đảo

Lấy nội dung hiện tại cho kiến trúc đảo
GET/island/{islandID}/{areaID}/content

Trả về nội dung tương ứng khi người dùng tap vào kiến trúc nào đó; nội dung trả về sẽ tùy thuộc số điểm của người dùng và kiến trúc tương ứng, ví dụ:

  • ở điểm = 0, Đảo Mầm DÆ°a > Tòa Thị Chính sẽ trả về video giới thiệu thời lượng 1 phút

  • ở điểm = 1, Đảo Mầm DÆ°a > Tòa Thị Chính sẽ trả về video tập 1 thời lượng 2 phút

  • ở điểm = 2, Đảo Mầm DÆ°a > Tòa Thị Chính sẽ trả về game chọn hình

  • v.v…

Phương thức gọi: public-facing API

Example URI

GET /island/mam_dua/toa_thi_chinh/content
URI Parameters
HideShow
islandID
string (required) Example: mam_dua

ID của đảo

areaID
string (required) Example: toa_thi_chinh

ID của kiến trúc

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  type: "video",
  details_endpoint: "/vod-item/{vodID}",
  consumption_endpoint: "/island/mam_dua/toa_thi_chinh/consume/video/{vodID}",
  vodID: "abc",
  point: 1
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  type: "game",
  details_endpoint: "/game/{gameID}",
  consumption_endpoint: "/island/mam_dua/toa_thi_chinh/consume/game/{gameID}",
  gameID: "abc",
  point: 1
}

Xác nhận xem video

Xác nhận xem video
4059883798/island/{islandID}/{areaID}/consume/video/{vodID}

Xác nhận hành động xem phim tương ứng với kiến trúc. Khi gọi vào endpoint này lần đầu tiên, người dùng sẽ nhận được điểm thưởng tương xứng với video.

Phương thức gọi: public-facing API

Example URI

POST /island/mam_dua/toa_thi_chinh/consume/video/abc
URI Parameters
HideShow
islandID
string (required) Example: mam_dua

ID của đảo

areaID
string (required) Example: toa_thi_chinh

ID của kiến trúc

vodID
string (required) Example: abc

ID của video

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Response  200

Xác nhận chơi game

Xác nhận chơi game
POST/island/{islandID}/{areaID}/consume/game/{gameID}

Xác nhận hành động chơi game tương ứng với kiến trúc. Khi gọi vào endpoint này lần đầu tiên với các câu trả lời đúng, người dùng sẽ nhận được điểm thưởng tương xứng với game.

Phương thức gọi: public-facing API

Example URI

POST /island/mam_dua/toa_thi_chinh/consume/game/abc
URI Parameters
HideShow
islandID
string (required) Example: mam_dua

ID của đảo

areaID
string (required) Example: toa_thi_chinh

ID của kiến trúc

gameID
string (required) Example: abc

ID của game

Request
HideShow
Headers
X-SSO-TOKEN: xyz
Body
{
  answer1: 0,
  answer2: 1,
  ...
}
Response  200

Generated by aglio on 29 Nov 2017