megaads/apify

A pretty library to help developers build RESTful APIs lightly, quickly and properly even without writing code

Apify

A pretty library to help developers build RESTful APIs lightly, quickly and properly even without writing code., _(*1)

It's always easy to customize to suit any need such as defining data relationships, authorization, caching, communicating or integrating into other systems., _(*2)

Features

• Serves RESTful APIs for any MySql database
  • Pagination
  • Sorting
  • Selection
  • Grouping, Having
  • Filtering
  • Relationships
  • Metadata
• Supports Event Bus

Using Apify

• Apify client for PHP: https://github.com/megaads-vn/apify-client-php
• Use HTTP clients like Postman to invoke RESTful API calls.
• Combine with API Gateway is also recommended to build a completely development environment for microservice.

Installation

Apify is packed as a composer package. So it's installed quickly in 2 steps 1. Require the composer package, _(*3)

`composer require megaads/apify`

1. Register the provider:, _(*4)

   Megaads\Apify\ApifyServiceProvider, _(*5)

System requirements

• PHP: >= 5.6
• Laravel/ Lumen Framework: 5.4.*
• MySQL
• Message queue server: optional

API Overview

Pagination

/api/post?page_id=2&page_size=20

Sorting

Order by multiple columns using sorts parameter, _(*6)

Sort ascending

/api/post?sorts=user_id

Sort descending

/api/post?sorts=-created_at

Sort by multiple columns

/api/post?sorts=user_id,-created_at

Selection

Select columns from the records using fields parameter. SQL aggregate functions such as COUNT, MAX, MIN, SUM, AVG, SQL aliases are also available, _(*7)

/api/post?fields=id,content,user_id,sum(view_count) as view_sum

Group By

Group the result-set by one or more columns using groups parameter and combine with aggregate functions using Selection, _(*8)

/api/post?fields=user_id,sum(view_count)&groups=user_id

Filtering

Apify supports filtering records based on more than one AND, NOT condition by using comma. For example:, _(*9)

/api/post?filters=user_id=1,status={enabled;pending},tile~hello,view_count!=null

Complex conditions that combine AND, OR and NOT will be available soon., _(*10)

Scope functions

/api/order?scopes=orderMeta(values=[adwords,123123];keys=[from,campaign_id]),customer(keyword=nguyen van nam)

namespace App\Models;

class Order extends \Megaads\Apify\Models\BaseModel
{
    public function scopeCustomer($query, $params) {
        if (isset($params['keyword'])) {
            //do something
        }
    }

    public function scopeOrderMeta($query, $params) {
        if (isset($params['keys']) && isset($params['values'])) {
            //do something
        }
    }
}

Entity conventions

Apify works by a simple mechanism, looking for a model class that correspond to the API entity, otherwise the API entity will be matched to a suitable DB table. That means no model class is required to create, do it only in the case of defining relationships, customizing., _(*11)

So API entity name should follow one of the conventions:, _(*12)

• The API entity name is the same as a model class name, _(*13)

• Or the API entity name in snake_case that correspond to a model class with the name in CamelCase, _(*14)

• Or the API entity name is the same as a DB table name, _(*15)

Relationships

Apify is packed into a Laravel/ Lumen package so relationships also are defined as methods on Eloquent model classes., _(*16)

See Laravel docs for details: https://laravel.com/docs/5.6/eloquent-relationships, _(*17)

Let's consider the following relationship definations:, _(*18)

• A Nation has many City (one-to-many relationship)

namespace App\Models;
class Nation extends \Apify\Models\BaseModel {
    protected $table = 'location_nation';
    public function cities() {
        return $this->hasMany('App\Models\City', 'nation_id', id);
    }
}

• A City belongs to a Nation (many-to-one relationship)
• A City has many District (one-to-many relationship)

namespace App\Models;
class City extends \Apify\Models\BaseModel {
    protected $table = 'location_city';
    public function nation() {
        return $this->belongsTo('App\Models\Nation', 'nation_id');
    }
    public function districts() {
        return $this->hasMany('App\Models\District', 'city_id', id);
    }
}

• A District belongs to a City (many-to-one relationship)

namespace App\Models;
class District extends \Apify\Models\BaseModel {
    protected $table = 'location_district';
    public function city() {
        return $this->belongsTo('App\Models\City', 'city_id');
    }
}    

Selection on relationships

Apify provides the ability to embed relational data into the results using embeds parameter, _(*19)

For example, _(*20)

/api/nation?embeds=cities

/api/city?embeds=nation,districts

/api/district?embeds=city

Even nested relationships, _(*21)

/api/nation?embeds=cities.districts

/api/district?embeds=city.nation

Filtering on relationships

/api/city?filters=nation.location_code=EU,districts.name~land

Metric

metric=get (by default): Retrieve all records that match the query

/api/post

or, _(*22)

/api/post?metric=get

Response format, _(*23)

{
    "meta": {
        "has_next": true,
        "total_count": 100,
        "page_count": 2,
        "page_size": 50,
        "page_id": 0
    },
    "result": [],
    "status": "successful"
}

metric=first: Retrieve the first record that matchs the query

/api/post?metric=first

Response format, _(*24)

{    
    "result": {},
    "status": "successful"
}

metric=count: Retrieve the number of records that match the query

/api/post?metric=count

Response format, _(*25)

{    
    "result": 50,
    "status": "successful"
}

metric=increment/ decrement: Provides convenient methods for incrementing or decrementing the value of a selected column

/api/post?metric=increment&fields=view_count

Response format, _(*26)

{    
    "result": 1,
    "status": "successful"
}

Event Bus

Is being updated ..., _(*27)

.env configurations

Authenticate Apify & authorize Apify?

Read docs here : https://github.com/megaads-vn/apify/blob/master/README-AUTH.md, _(*28)

License

The Apify is open-sourced software licensed under the MIT license, _(*29)

Contact us/ Instant feedback

Email: phult.contact@gmail.com, _(*30)

Skype: phult.bk, _(*31)

If you find a bug, please report it here on Github., _(*32)