sxapi-core project
Build status :
sxapi for simple and extensible api
(Application Programming Interface) is an an open-source framework for
quickly building simple and small API based on microservice architecture.
Very light (application less than 100Ko, full container stack for less than 30Mo)
and configured with a single json file, you can build instantly small atomic
API endpoints as well as fully featured enterprise-sized API.
Getting Started
sxapi is shipped in 3 ways :
- container image published in dockerhub public registry
The simplest and fastest way to get a running sxapi application is to use the
public docker image. For more information on how to run your first sxapi
application using sxapi docker image, please read the
Using docker image user guide
- npm module published in npm public database
If you plan to develop your own component or embed you api into another
application, you should be more interested by the npm method. For more
information on how to run your first sxapi application using sxapi npm module,
please read the Using nm module user guide
- source code published in github
If you plan to extend sxapi capabilities with your own component, change
default software design, extend core functinalities or more globaly improve
this application, please read the Using source code user guide
Want to try ?
To try this application before working on it, the easiest way
is to use the container version. Follow theses steps to run
a sxapi application within the next couple of minutes.
(You can skip the first step if you already have docker
installed and running)
1. Install and start docker
Theses command are for a Red Hat Linux like
environement (Fedora, CentOS, RHEL, Suse). Please adapt yum
command to the
apt-get
equivalent if you are using a Debian like system (Ubuntu, Debian)
sudo yum install -y docker
sudo service docker start
For more information on how to install and execute a docker runtime, please see
the official docker installation guide
After installation, pay attention to your user authorisation. Your current user
must interact with the docker daemon.
2. Create your working directory
To run you test in a sandbox, you should isolate your sxapi test from
your current work by creating a working directory.
mkdir ~/test-sxapi
cd ~/test-sxapi
3. Get the sxapi container image
Use docker command to get sxapi container image from the docker hub registry.
This will update your local docker image cache.
docker pull startx/sxapi:latest
4. Create your sxapi.json configuration file
Create a file named sxapi.json
vi ~/test-sxapi/sxapi.json
Edit it with the following content
{
"name": "sample-api",
"description": "my sample api using sxapi-core framework",
"version": "0.0.0",
"debug": true,
"log": {
"filters": {
"level": "0,1,2,3,4",
"type": "debug,info,error,warn"
}
},
"server": {
"endpoints": [
{
"path": "/",
"body": "<html><head></head><body><h1>My sample API</h1></body></html>"
}
]
}
}
You can change name
, description
, version
and
server.endpoints.body
with personalized content
5. Run your application
docker run -d -p 8080:8080 -v ~/test-sxapi/sxapi.json:/conf/sxapi.json:ro startx/sxapi
6. Explore your api
Connect to http://localhost:8080/
with your favorite navigator. You should
see an html message "My Sample API".
Creating your own API
sxapi-core come with many components to help you build your own api. As soon as
you have an api instance working, you should focus on making change to your
sxapi.json
config file and implement api endpoints you want to create.
To help you understand how you can configure your api, you can :
- Visit sxapi-core official documentation and read carefully
the develop section
- Visit sxapi-sample project and
explore sample config file to help find sample code or ready-to-use config file
For more information on how to use this project as a container,
see use docker image
For more information on how to change your configuration file and create an API
relflecting your needs, please read carefully our
building api user guide
Documentation
If you want to have more information on how to install, develop and run this
framework and use it in your project, please read the
full documentation or our user guides
sections :
- Install sxapi
- Configure sxapi
- Run sxapi
- Develop sxapi resource
Troubleshooting
If you run into difficulties installing or running sxapi, please
report issue for installer
or issue for sxapi.
Built With
Contributing
Please read contributing guide for details on
our code of conduct, and the process for submitting pull requests to us.
Authors
This project is mainly developped by the startx dev team.
You can see the complete list of contributors who participated in this project
by reading CONTRIBUTORS.md.
License
This project is licensed under the GPL Version 3 -
see the LICENSE.md file for details