Commit b6904553 authored by hellekin's avatar hellekin

Update README

- Added a prominent message about using the API key.

  The public API key is not technically necessary (we could accept
  indiscriminate requests) but prevents responding to Web robots
  harvesting random resources.

- Added internal links to sections to ease reading.
parent 4539e9da
# IN COMMON API
## [Introduction](https://api.incommon.cc/intro)
1. [Introduction & Usage](#intro)
2. [Installation & Configuration](#install)
3. [Contributing & Reporting](#contribute)
4. [Licensing](#license)
<a name="intro"></a>
## [Introduction](https://api.incommon.cc/intro) & Usage
[![pipeline status](https://gitlab.com/incommon.cc/incommon-api/badges/master/pipeline.svg)](https://gitlab.com/incommon.cc/incommon-api/commits/master)
......@@ -9,6 +17,32 @@
This is a Rails 5 API-only application using Ruby 2.5.3 (MRI) and PostgreSQL 10
with PostGIS extensions.
### Usage
**Always use an API key**. The default, public API key is: `23d8009f-f2ec-44b6-bcbe-58ad1d3af10b`.
In your requests to the IN COMMON API, you can use it as a query parameter:
``` shell
curl https://api.incommon.cc/?api_key=23d8009f-f2ec-44b6-bcbe-58ad1d3af10b
```
<a name="install"></a>
## Installation & Configuration
1. [System Dependencies](#system-dependencies)
2. [Configuration](#configuration)
3. [Testing](#testing)
4. [Services](#services)
5. [Deployment](#deployment)
Discussion: https://talk.incommon.cc/c/api/support
<a name="system-dependencies"></a>
### System Dependencies
It is developped on Gentoo / GNU/Linux and should support any GNU/Linux system
......@@ -17,9 +51,12 @@ in production. For Ruby, we recommend using [ruby-install] and [chruby]!
[ruby-install]: https://github.com/postmodern/ruby-install
[chruby]: https://github.com/postmodern/chruby
<a name="configuration"></a>
### Configuration
Examples show the case of Debian-based systems. <abbr title="Your Mileage May Vary">YMMV</abbr>
Examples show the case of Debian-based systems. <abbr title="Your Mileage May Vary">YMMV</abbr>.
#### NginX + Puma
......@@ -72,6 +109,9 @@ Please refer to [doc/database_setup.md].
[doc/database_setup.md]: ../doc/database_setup.md
<a name="testing"></a>
### Testing
We recommend using Guard: `bundle exec guard`.
......@@ -82,12 +122,18 @@ Please refer to [RSpec documentation] to run or write individual tests.
[RSpec documentation]: http://rspec.info/documentation/3.8/rspec-core/
<a name="services"></a>
### Services
Writing to the database **will** use Job queues running [Sidekiq].
Writing to the database **will** use Job queues running [Sidekiq] (or similar).
[Sidekiq]: https://github.com/mperham/sidekiq
<a name="deployment"></a>
### Deployment
- always use `db/structure.sql` and database import to get started. It will save
......@@ -100,7 +146,10 @@ Writing to the database **will** use Job queues running [Sidekiq].
[LetsEncrypt]: https://letsencrypt.org/
## Contributing
<a name="contribute"></a>
## Contributing & Reporting
We're a welcoming community. We expect every contributor to be respectful of
each other and the [IN COMMON Charter].
......@@ -119,6 +168,9 @@ Our development community gathers at <https://talk.incommon.cc/c/api>.
See <https://talk.incommon.cc/t/welcome-developers/127/1>
<a name="license"></a>
## Licensing
`incommon-api` Copyright © 2018 [IN COMMON Collective] and contributors.
......@@ -136,3 +188,5 @@ You should have received a copy of the GNU Affero General Public License along
with this program. If not, see <https://www.gnu.org/licenses/>.
See [LICENSE](../LICENSE.md)
[IN COMMON Collective]: https://talk.incommon.cc/groups/incommon
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment