aspnmy / phalapi Goto Github PK

##PhalApi - V1.3.5 - English Version
PhalApi, π Framework for short, is a light-weight framework which focus on how to develop API faster and simpler. It:

• aims to continuous deliver available API services rapidly and stabely.
• foucus on TDD, DDD, XP and alige development.
• has many libraries, which can use optionaly according your projects need.
• supports HTTP, SOAP and RPC protocol, can be used to build micro services, RESTful APIs and WeWeb Services.

We share our codes, our product and our mind in PhalApi, please feel free to use it. For more information, check www.phalapi.net.

PhalApi中文版请访问release分支。

###Tutorial This article is composed with three parts as below:

• PART 1：Installation, online demo and online API doucements.
• PART 2：rapid development, unit tests, framework structure, SDK packages and external librareis.
• PART 3：backgroud review, contributors, licience and changelog.

Vist wiki for more details.

##1-1, Installation

• download the lastest version from release-en
• we recommend deploy PhalApi on Linux
• PHP >= 5.3.3

Open a browser and visit Installation Tutorial after download PhalApi and unzip on your server(we recommend nginx, and set the root to /path/to/PhalApi/Public):

http://localhost/PhalApi/Public/install/

And then visit the default API service to varify installation.

http://localhost/PhalApi/Public/demo/

More other ways to create your project, please check Create your project.

###Upgrade and share We will do our best to keep perfect compatibility during version upgrade. When you need to upgrade PhalApi, you just need one simple step: replace ./PhalApi/PhalApi with the lastest core folder. That is it!

If we need to share PhalApi, we can move ./PhalApi/PhalApi to anywhere, and alter the including path in ./PhalApi/Public/init.php(NOTE, it will affects some shells). e.g:

// $ vim ./PhalApi/Public/init.php
require_once API_ROOT . '/path/to/PhalApi/PhalApi.php';

##1-2, Online demo 1, Default API service:

http://demo.phalapi.net/

2, Demo API with params:

http://demo.phalapi.net/?service=Default.Index&username=github

{
    "ret": 200,
    "data": {
        "title": "Hello World!",
        "content": "Hello github, Welcome to use PhalApi!",
        "version": "1.3.4",
        "time": 1473863280
    },
    "msg": ""
}

3, Request a service not found:

http://demo.phalapi.net/?service=Demo.None

{
    "ret": 400,
    "data": [],
    "msg": "no such service as Demo.None"
}

##1-3, Online API documents(auto generated) Afster project APIs have been written in PhalApi specified format, PhalApi will auto generate online API list documents and online API detail documents, which can provide client developers with realtime API signature and response structure.

1, Online list documents
We can list all API services under our project by visiting the listAllApis.php in the related project, e.g:

http://demo.phalapi.net/listAllApis.php

2, Online API detail documents
Furthermore, We can check more detail about an API servcie by visiting the checkApiParams.php with param ?service=xxx.xxx, e.g:

http://demo.phalapi.net/checkApiParams.php?service=Default.Index

##2-1, Rapid Development 1, Hello World! Create an API file ./Demo/Api/Welcome.php with the code as below:

<?php
class Api_Welcome extends PhalApi_Api {

	public function say() {
		$rs = array();
		$rs['title'] = 'Hello World!';
		return $rs;
	}
}

2, Visit the API
We can call an API service by visit the url as : host + entrance + ?service=XXX.XXX. In the case, the url is:

http://localhost/Public/demo/?service=Welcome.Say

3, API reponse
The API will reponse with json data as :

{"ret":200,"data":{"title":"Hello World!"},"msg":""}

4, Screenshot

##2-2, API unit tests The code can't be tested is bad.

When develop API with PhalApi, we strong recommend following TDD, in order to build an auto testing system and keep compatibility. According to BUILD-OPERATE-CHECK pattern, we can create unit tests for the API /?service=User.GetBaseInfo&userId=1:

    /**
     * @group testGetBaseInfo
     */ 
    public function testGetBaseInfo()
    {
        //Step 1. Contruct request URL
        $str = 'service=User.GetBaseInfo&userId=1';

        //Step 2. Exec request(imitate API request)	
        $rs = PhalApi_Helper_TestRunner::go($url);

        //Step 3. Verify
        $this->assertNotEmpty($rs);
        $this->assertArrayHasKey('code', $rs);
        $this->assertArrayHasKey('msg', $rs);
        $this->assertArrayHasKey('info', $rs);

        $this->assertEquals(0, $rs['code']);

        $this->assertEquals('dogstar', $rs['info']['name']);
        $this->assertEquals('oschina', $rs['info']['from']);
    }

Running screenshot:

We have sticked to writting unit tests for the core codes in PhalApi all the time, and out code coverage is high as 96%.

##2-3, Main Structure

.
│
├── PhalApi         //PhalApi framework core codes, upgrade the whole folder if need
├── Library         //PhalApi external libraries, you can add any library you need
├── SDK             //PhalApi client SDK in different programming languages
│
│
├── Public          //Public entrance
│   └── demo        //Demo service entrance
│
│
├── Config          //Project common config, including: app.php, sys.php, dbs.php
├── Data            //Project data
├── Language        //Project common translation
├── Runtime         //Project runtime folder, saving logs, etc. you can change it with ls command
│
│
└── Demo            //Demo API sevices, you can rename it as you want, and creae multi projects as you want
    ├── Api             //API controller level
    ├── Domain          //API domain level
    ├── Model           //API data level
    └── Tests           //API unit tests

##2-4, Client SDK based on API Structured Query Language(ASQL) Currently, we have these SDKs as below:

• JAVA client SDK
• Objective-c client SDK
• PHP client SDK
• C# client SDK
• Javascript client SDK
• Golang client SDK
• React-Native client SDK
• Ruby client SDK

We can describe an API request as one sentence with API Structured Query Language. Take Java as example:

PhalApiClientResponse response = PhalApiClient.create()
       .withHost("http://demo.phalapi.net/")
       .withService("Default.Index")          //API service
       .withParams("username", "dogstar")     //API params
       .withTimeout(3000)                     //API timeout
       .request();

##2-5, PhalApi-Library external libraries More external libraries are valiable on PhalApi-Library

##3-1, Background review We provide PhalApi because we hope to :

• Firstly, support light-weight API projects rapid development;
• Secondly, explain how to design, develop and mantain APIs in face of big data;
• Last but not least, share some good mind, skills, tools and best practices.

In summery, welcome to use PhalApi! We will keep devoting ourself into PhalApi and keep it full of energy, reponseable for open source framework!

##3-2, Join Us Obviously, this is just the beginning, and there is a long way to go. PhalApi is not our (develop team) framework, but our (all of us) framework. Let's do something meaningful when we are young. Welcome to join us anytime!

Contributors:

• Aevit
• dogstar
• George
• Scott
• Summer
• zz.guo（郭了个治浩）
• 小艾
• 大蝉
• 冰霜
• 火柴
• 黄苗笋
• 文振熙（喵了个咪）
• 爱编程的小逗比
• ... ...

##3-3, License PhalApi is an open source framework, and promises keep free forever. PhalApi is under GPL, more details on License.

##3-4, Change Logs Change Logs.