Awesome

NamesAPI

NamesAPI is a RESTful API to provide metadata about people names (gender, language, country, meaning, procedence, popularity, composition, etc.), also provide some mechanisms to make some Data Mining using Open Graph of Facebook API to obtain some data for the project.

NamesAPI is developed using Laravel and MongoDB as default database manager, through the jenssegers/laravel-mongodb repository.

How To Install and configure

• If you going to use MongoDB as database manager, make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongo.installation.php. Of course you will need a local or remote MongoDB instance which provide you the API data.

Note: In Ubuntu 14.04 issue:

$ sudo apt-get install php5-mongo

For other OS or distros use the official PHP or MongoDB documents.

• Download the project source, then you must configure your sensitive data like database username or password. To do this, NamesAPI uses '.env.*.php' files, (see .env.example and/or laravel sensitive data for details) in this files you have to stablish your database connection data (database hosts and name, port, user and password ) the crypt key (is different for every Laravel instance), the default project url and the access_token.

Note: The access_token is a public key obtained from your own Facebook app. More details in Facebook Access Token Tool.

Note: You must have at least a file called '.env.php' (notice the dot at the beginning) to apply the config on all environments. If you want to set different sensitive data values by the environment you must first configure every desired environment in laravel (see laravel environment configuration for details) and then create a file called '.env.environmentName.php for example: '.env.local.php' or '.env.develop.php'. (see laravel sensitive data for details)

• Finally, to install all the project dependencies and finish your installation, run:

composer install

(see composer.json file for details or composer website)

Basic database Schema

Below is the base data scheme, stored into the MongoDB database. Take into account that if you will use Moloquent (the laravel-mongodb ORM) is not neccessary to define a previus scheme because Moloquent will do it for you.

To create your own database instance using other DBM or ORM you can use the following data schema:

    "_id" : "Generated By Names Model (SHA1)",
    "value" : "the name value",
    "popularity" : [0-5],
    "gender" : "m|f",
    "composition" : [1,2],
    "meaning" : "Some name meaning",
    "procedence" : "The name procedence",
    "country" : "country ISO2 code",
    "language" : "Language ISO2 code",
    "updated_at" : ISODate("YYYY-MM-DDTHH:MM:SSZ"),
    "created_at" : ISODate("YYYY-MM-DDTHH:MM:SSZ")
    

Take into account that NamesAPI provide a model called "Name" (see the models folder) which provides a method (setAttributes) to stablish the '_id' attribute automatically, based on the value, gender, country and language (similarly that '__construct').

Aditional models

NamesAPI provide other three models:

• Api: This model don't use any ORM because not going to interact with any database. Contain useful functions for the API data generation.
• Country: This model bring all the properties to create Country objects and interact with the database through the ORM Moloquent.
• Language: Similar to Country, allow easily create Language objects and use the ORM.

Contributing To NamesAPI

All issues and pull requests should be filed on the JuanDMeGon/NamesAPI repository.

If you want to collaborate to improve the translation of readme.md file, syntax and grammar, you are welcome :).