A RESTful API implementation turning information from GM API into clear format on Smartcar endpoints
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
Following are the prerequisites to run this program you need to install and how to install them
python3 - The project was built using python 3.6.3, to see which version you have installed
$ python3 --version
Then you may visit the following guidance to install it in your system For Linux For MacOS
pip - A tool for python library quick installation Follow this to check and install
virtualenv - A tool to create isolated python environments to help manage dependencies and versions Follow this to check and install
Here is the guide to get a development environment of this project running for you
Please using this github repo url by clicking the button at the upper-right corner of this page and clone the project into your local directory, then in that directory, make and activate an virtualenv for this project(best practice is to name the env using the same name as the project folder, which make the structure of files more consice, I didn't realize it when initialized this), remember to install the requirements for this virtualenv, now you are all set to play with the program.
$ mkdir your-directory; cd your-directory
$ git clone <project-url>
$ virtualenv your-env (Note if you have several versions of python installed, use the command below)
$ virtualenv -p /usr/bin/python3.6(directory of python installed) your-env
$ source your-directory/your-env/bin/activate
$ pip install -r requirements.txt
Under smartcar, make sure you can see the following file hierarchy. Note that this project was structured as a DRF project called smartcar, with all the features built in a DRF application inside this project called vehicles; the whole project was developed in a virtual env called smart-api and under the folder called smartcar. The requirement.txt is for holding the dependencies imported into this env.
└── smartcar
├── db.sqlite3
├── manage.py
├── smartcar
│ ├── __init__.py
│ ├── __pycache__
│ │ ├── __init__.cpython-36.pyc
│ │ ├── settings.cpython-36.pyc
│ │ ├── urls.cpython-36.pyc
│ │ └── wsgi.cpython-36.pyc
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py
└── vehicles
├── __init__.py
├── __pycache__
│ ├── __init__.cpython-36.pyc
│ ├── admin.cpython-36.pyc
│ ├── models.cpython-36.pyc
│ ├── serializers.cpython-36.pyc
│ ├── urls.cpython-36.pyc
│ └── views.cpython-36.pyc
├── admin.py
├── apps.py
├── migrations
│ ├── 0001_initial.py
│ ├── __init__.py
│ └── __pycache__
│ ├── 0001_initial.cpython-36.pyc
│ └── __init__.cpython-36.pyc
├── models.py
├── serializers.py
├── test
│ ├── __init__.py
│ ├── __pycache__
│ │ ├── __init__.cpython-36.pyc
│ │ ├── test_api.cpython-36.pyc
│ │ ├── test_serializer.cpython-36.pyc
│ │ └── test_views.cpython-36.pyc
│ ├── test_api.py
│ ├── test_serializer.py
│ └── test_views.py
├── urls.py
└── views.py
If you see so, it is time to run the server under smartcar/smartcar
$ python3 manage.py runserver
Now you may monitor the HTTP requests information and their responses status in this window for each operation. You may also visit the simple browsable UI of this API using your favorite browser.
http://127.0.0.0:8000/vehicles
Please reference the The Smartcar API Spec for how to visit each endpoint RESTfully
Note that if you want to clean up all of the endpoints or you changed something in the source code or something just messed up and you don't know why:), it is recommended to run the clean.py script offered along side the manage.py and application to clean the cache and redo the database migrations. To do this, run
$ python3 clean.py
The tests for this project were written using Django's unittest framework. Here is how to run the automated tests for this system. Under smartcar/ (same location to run the server), run the command below, optional is for getting more information
$ python3 manage.py test -v(optional) 2(optional)
The results will be shown as "OK" if all of the test cases are passed, otherwise "FAIL|ERROR" with detail information
The tests written for this application were based on both features of different endpoints and functional modules of DRF framework.
Due to the limit of time, the test cases offered here are not be able to cover all of the function points and use cases. For example, in test_view.py and test_serializer.py, only tests for vehicle info and security info offered for now, other tests could be written following the same structures and idea.
- views tests - Testing the flows from objects creation to object retrieving through GET and POST requests to Smart API endpoints
- api tests - Testing the complete flow for every Smart API endpoint from sending requests to GM API endpoints, getting information from responses, parsing and construcing data for requesting Smart API and validating the responses finally
- serializer tests - Testing the flow from objects creation based on models to serializing them to valid data type
- models - Models are designed to store the objects with some structures into database. In this project, different resources have their own model but related through some attributes.
- serializers - Serializers are used to serializing the instances into representations such as json format in our case. In this project, they are highly uniform with the models.
- views - Views are how data interacting with the web APIs using requests and responses. In this project, views were created based on funcionality of the endpoints and the request methods.
- urls - Urls are url patterns matching resources to API endpoints. In this project, urls were formed along with the resource name and query parameter using regex.
This is so far the only version available from this author. Later development and iteration is recommended to use version management tools for versioning.
- Amber Wang - Initial work - AmberWangjie
Not applicable yet.
- This project was technically supported by Smartcar Inc, really appreciate the help from their team!
Here is a to-do list of this project to get it more complete and function-well
- engine POST request and response customization
- complete test case
- add user authentications and permissions