OVERVIEW

เอกสารนี้เป็นเอกสารที่จัดทำเพื่อเป็น Guideline สำหรับการเขียน API เพื่อเชื่อมต่อกับ Application ของบริษัท CPN และจะเป็นมารตฐานต่อๆไป ในการเชื่อมต่อกับ Service ของบริการที่จะมีขึ้นต่อๆไปในอนาคต


* แต่ถ้า Service ที่ต้องการจะนำมาเชื่อมต่อใน Application นั่นมี API และ API Document ที่ครบอยู่แล้ว สามารถใช้ API และ API Document ของทาง Service นั้นๆได้เลย แต่ต้องดำเนินการส่งชุดเอกสารและควรมีตัวทดสอบการยิง API เช่น Postman ให้เพื่อสามารถทดสอบการทำงานของ API ได้



GUIDELINE

ข้อกำหนดชื่อตัวแปรต่างๆ
1. ตัวอักษรตัวแรกของคำเป็นตัวเล็ก เช่น name, mobile, email หรือ key
2. หากเป็นคำที่ยาวมีหลายพยางค์ให้ตัวขึ้นต้นเป็นตัวใหญ่ด้วย เช่น firstName, fastName หรือ customerId
3. ชื่อฟังชั่นที่เป็น URL เป็นตัวเล็กทั้งหมดหากชื่อฟังชั่นยาวให้ขั้นด้วย "_" เช่น login, list_news หรือ list_customer_verify

* ค่าเหล่านี้เป็นตัวกำหนดทั้งค่า Parameter ที่ Post ไปขอข้อมูลและค่า Return ที่ส่งข้อมูลกลับมา



1. URL

เป็นการกำหนดชื่อให้กับ URL ในการเรียกใช้ API รูปแบบของ URL ให้กำหนดเป็นค่า ConfigURL แล้วตามด้วยชื่อฟังชั่น ดัวอย่างข้างล่าง

URL {configURL}/login
TYPE POST

หรือ

URL {configURL}/list_customer_verify
TYPE POST



2. Post Parameter

เป็นค่า Parameter ที่ใช้ส่งจาก Application เพื่อขอข้อมูล Return จาก Service ที่ต้องการนำมาเชื่อมต่อ (ให้เขียนตัวรับค่าเป็น Raw file ที่เป็นรูปแบบ Json)

PARAMETER DESCRIPTION
apiKey ใช้แทน User และ Password ในการกำหนดสิทธิ์การใช้งานและเข้าข้อมูลของ API
{parameter} ค่าที่ api ต้องการ
page เลขหน้า เริ่มต้นหน้าแรกที่ "0"

(option) ใช้สำหรับ API ที่เป็น List
pageAmount จำนวน Item ต่อ 1 หน้า

(option) ใช้สำหรับ API ที่เป็น List

Example 
{
    "apiKey" : "abcdefghijk",
    "id" : "12",
    "page": "0",
    "pageAmount":"20"
}

* หากต้องการความปลอดภัยเพิ่มขึ้น ให้กำหนดรูปแบบการเข้ารหัสใสการส่งข้อมูล เป็น JWT หรือ AES โดยกำหนด Key ในการถอดรหัส



3. Return Parameter

ค่า Return ที่ได้มาจากการเรียก API แสดงข้อมูลออกมาในรูปแบบ Json จะถูกแบ่งออกเป็น 2 ส่วน คือ Header และ Body เพื่อใช้แยกในส่วนที่ใช้ตรวจสอบ กับ ข้อมูลที่จะทำไปใช้จริง ซึ่งข้อมูลที่จะนำไปแสดงมี 2 รูปแบบคือ

3.1 รูปแบบ Object

header ใช้แสดงค่าสำหรับเช็คข้อมูลและสถานะการร้องขอ ข้อมูล API
body ข้อมูลจริงที่จะถุกนำไปใช้งาน

Header parameter

PARAMETER DESCRIPTION
resultCode เป็น Code ที่ส่งมาจาก Server ใช้สำหรับตรวจสอบสถานะ Error ต่างๆ 200("success") 404 ("file not found")
message แสดงข้อความสถานะของเซฟเวอร์และ API เช่น "success" หรือ "server down"

Example
header 
{
    "resultCode" : "200",
    "message" : "success"
}
body 
{
    "staffId" : "11",
    "staffTitileName" : "นางสาว",
    "staffFirstName" : "อารีย์",
    "staffLastName" : "นารถ"
}

Example (Full Code) 

{
    "header" : {
        "resultCode" : "200",
        "message" : "success"
    },
    "body" : {
        "staffId" : "11",
        "staffTitileName" : "นางสาว",
        "staffFirstName" : "อารีย์",
        "staffLastName" : "นารถ"
    }
}



3.2 รูปแบบ Array

ใช้สำหรับแสดงโครงสร้างข้อมูลที่เป็น List หลายๆ Item

header ใช้แสดงค่าสำหรับเช็คข้อมูลและสถานะการร้องขอ ข้อมูล API
body แสดงชุดข้อมูลในรูปแบบ Array

Header parameter

PARAMETER DESCRIPTION
resultCode เป็น Code ที่ส่งมาจาก Server ใช้สำหรับตรวจสอบสถานะ Error ต่างๆ 200("success") 404 ("file not found")
message แสดงข้อความสถานะของเซฟเวอร์และ API เช่น "success" หรือ "server down"
pageAmount จำนวน Item ต่อ 1 หน้า
page เลขหน้า
pageMax จำนวนหน้าทั้งหมด

Example
header 
{
    "resultCode" : "200",
    "message" : "success",
    "pageAmount" : "10",
    "page" : "0",
    "pageMax" : "1"
}
body 
{
    "projectId" : "11",
    "projectName" : "รามอินทรา-เสรีไทย",
    "projectImage" : "http://www...com/images/projectImage1.png",
},{
    "projectId" : "12",
    "projectName" : "ปิ่นเกล้า-เพชรเกษม",
    "projectImage" : "http://www...com/images/projectImage2.png",
},
{
    "projectId" : "13",
    "projectName" : "สุขุมวิท",
    "projectImage" : "http://www...com/images/projectImage3.png",
},...


Example (Full Code) 

{
    "header" : {
        "resultCode" : "200",
        "message" : "success",
        "pageAmount" : "10",
        "page" : "0",
        "pageMax" : "1"
    },
    "body" : [
        {
            "projectId" : "11",
            "projectName" : "รามอินทรา-เสรีไทย",
            "projectImage" : "http://www...com/images/projectImage1.png",
        },{
            "projectId" : "12",
            "projectName" : "ปิ่นเกล้า-เพชรเกษม",
            "projectImage" : "http://www...com/images/projectImage2.png",
        },
        {
            "projectId" : "13",
            "projectName" : "สุขุมวิท",
            "projectImage" : "http://www...com/images/projectImage3.png",
        }
    ]
}