ឯកសារ API

GeoChat បានផ្តល់នូវអ្នកប្រើប្រាស់នូវ API Basic Auth ដើម្បីកំណត់ភាពត្រឹមត្រូវរបស់អ្នកប្រើប្រាស់។

End points មួយចំនួនដំណើរការបានទាំងauthenticated និង non-authenticated requests. បើសិនជាclient មិនsupport pre authentication នេះប្រហែលជាបញ្ហា។ នៅក្នុងករណីនេះ ?auth=true គួតែត្រូវបានបញ្ចូលទៅក្នុងQueryString ដើម្បីជំរុញប្រពន្ធ័មេកានិករបស់authentication មូលដ្ឋាន (Since 1.7.1)

រាល់សំណើរទាំរអស់អាចធ្វើបានតាមរយៈ SSL

Api ធ្វើការហៅយកលេខទំពរ័ដែលត្រឹមត្រូវគឺប្រើ1-based page index នៅក្នុង QueryString។ លទ្ធផលនឹងភ្ជាប់ជាមួយនូវដំណរភ្ជាប់ទៅកាន់ទំពរ័ខាងមុខនិងទំពរ័បន្ទាប់ បើសិនជាជាអាចប្រើដំណរភ្ជាប់ដែលល្អិតបំផុតជាមួយនិងទំនាក់ទំនងជាមួយទំពរ័ខាងក្រោយនិងទំពរ័បន្ទាប់។
បើសិនជាលេខទំពរ័មិនត្រឹមត្រូវនៅក្នុងQueryString, នោះវានឹងទៅកាន់ទំពរ័ដំបូងដោយស្វយ័ប្រវត្តិ។
លទ្ធផលគឺមានកំណត់តែ១០តែប៉ុណ្ណោះក្នុងមួយទំពរ័។

ជាឧទាហរណ៏លទ្ធផលនៃ http://geochat.instedd.org/api/foo/bar?page=2 នឹង:

<?xml version="1.0"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>...</title>
    <description>...</description>
    <atom:link rel="previous" href="http://geochat.instedd.org/api/foo/bar?page=1" />
    <atom:link rel="next" href="http://geochat.instedd.org/api/foo/bar?page=3" />
    <!-- items -->
  </channel>
</rss>

• ទាញយកពត៌មានរបស់អ្នកប្រើប្រាស់
• បង្កើតអ្នកប្រើប្រាស់
• កែប្រែពត៌មានរបស់អ្នកប្រើប្រាស់
• រាយឈ្មោះក្រុមអ្នកប្រើប្រាស់
• រាយឈ្មោះសំណើររបស់អ្នកប្រើប្រាស់
• រាយឈ្មោះការអញ្ជើញអ្នកប្រើប្រាស់
• ការបញ្ជាក់អ្នកប្រើប្រាស់

• បង្ហាញពត៌មានរបស់ក្រុម
• បង្កើតក្រុម
• កែប្រែការកំណត់របស់ក្រុម
• បញ្ជីឈ្មោះក្រុម
• បញ្ជីឈ្មោះសមាជិក្រុម
• ចូលរួមក្រុម
• ចាកចេញពីក្រុម
• អញ្ជើញអ្នកប្រើប្រាស់ចូលក្រុម- ទទួលយកសំណើររបស់អ្នកប្រើប្រាស់

• ទទួលសារ
• ផ្ញើសារ
• ផ្ញើសារទៅកាន់ក្រុម
• ទទួលសារពីក្រុម
• ទទួលសារពីអ្នកប្រើប្រាស់
• ទទួលសារសាធារណៈ

• សរុបរួម
• ប្រវត្តិនៃសារ
• ប្រវត្តិនៃសារក្នុងមួយProtocol
• ប្រវត្តិនៃបណ្តាញរបស់អ្នកប្រើប្រាស់
• ការអញ្ជើញដែលមិនទាន់បានសំរេច

• ពត៌មានទូទៅ
• ពត៌មានរបស់ក្រុមក្នុងSystem
• ពត៌មានមានសាររបស់System
• ពត៌មានសាររបស់System តាម Protocol
• បណ្តាញអ្នកប្រើប្រាស់របស់System
• ពត៌មានអ្នកដែលអញ្ជើញដែលមិនទាន់បានសំរេចក្នុងSystem
• រាប់ចំនួនអ្នកប្រើប្រាស់ក្នុងក្រុមមួយក្នុងSystem
• ពត៌មានរបស់អ្នកប្រើប្រាស់របស់System

API resources អាចត្រូវបានអ្នកប្រប្រាស់ធ្វើជាសំនើរជា ATOM ឬ RSS (វិធីមួយចំនួនអាអនុញ្ញាតិ KML និង CSV).

អ្នកអាចកំណត់ទំរង់នៃលទ្ធផលនៅក្នុងURI នៃសំនើរ។ រូបមន្តរបស់វាគឺ http://geochat.instedd.org/api/foo/bar.{format}, ឧទាហរណ៏ http://geochat.instedd.org/api/users/johndoe.rss នឹងផ្តល់លទ្ធផលជា RSS, និង http://geochat.instedd.org/api/users/johndoe.atom នឹងផ្តល់លទ្ធផលជា ATOM.

បើសិនជាមិនកំណត់ទំរង់ច្បាស់លាស់ទេ(ឧទា. http://geochat.instedd.org/api/users/johndoe) នោះវានឹងផ្តល់លទ្ធផលជា RSS.

អ្នកអាចមើលឧទាហរណ៏នៅក្នុងឯកសារនៃវិធី API នីមួយៗ។

នៅពេលដែលCodeមានកំហុសណាមួយកើតឡើង,​ នោះHTTP នឹងបង្ហាញដូចខាងក្រោម៖

• 404 Not Found: មាននយ័ថា អ្នកកំពុងដែលធ្វើសំនើរដែលគ្មានresource។
• 403 Forbidden: មាននយ័ថា អ្នកគ្មានសិទ្ធិក្នុងការប្រើប្រាស់resource ដែលអ្នកបានស្នើទេ។
• 401 Unauthorized: មានលក្ខណៈប្រហាក់ប្រហែលនិងចំនុចខាងលើដែរ, តែផ្តោតទៅលើការប្រើប្រាស់ដែលមានសិទ្ធិហើយតែមិនបានសំរេច ឬពុំទាន់បានផ្តល់អោយ។
• 400 Bad Format: មានប៉ារ៉ាមែត្រណាមួយខុស ឬរូបមន្តខុសក្នុងការធ្វើសំនើរ។

គំរូ PHP អាចរកបាននៅក្នុងfolder 'Samples/RestApi/PHP' នៃ source code របស់ GeoChat (google code link).

ដើម្បីអាចដំនើរការCodeគំរូនេះ, អ្នកចាំបាច់ត្រូវមាន web server ជាមួយនិង PHP (គំរូនេះត្រូវបានបង្កើតឡើងជាមួយនិង PHP 5.3.0, ប៉ុន្តែជាមួយនិង versions ផ្សេងទៀតក៏អាចដំណើរការដែរ) ហើយ 'php_curl' extension ត្រូវបានenable។ MagpieRSS ក៏មានតំរូវការដែរ, ប៉ុន្តែវាត្រូវបានបញ្ជូលរួចជាស្រេចនៅក្នុងsource code។ ទីតាំងURL សំរាប់ API service អាចត្រូវបានconfigure នៅក្នុង 'api.php', គ្រាន់តែកែឈ្មោះដែលបានដាក់អោយច្បាស់ 'BASE_API_URL'.

មានគំរូ៣សំខាន់ៗគឺ៖

• គំរូនៃក្រុម (group_example.php): បង្ហាញពត៌មានក្រុម, សារដែលនៅក្នុងក្រុមចុងក្រោយបំផុត និងអ្នកប្រើប្រាស់ដែលផ្ញើសារទៅកាន់ក្រុម។
• គំរូសារ (mymessages_example.php): បង្ហាញសាររបស់អ្នកប្រើប្រាស់។
• គំរូControl panel (controlpanel_example.php): បង្ហាញ 'my groups' (ក្រុមរបស់អ្នកប្រើប្រាស់) ហើយអោយអ្នកប្រើប្រាស់បង្កើតក្រុមថ្មី។

ចំណាំ: login របស់អ្នកប្រើប្រាស់មិនបញ្ជាក់កំណត់សំគាល់ទេ។