Skip to content
This repository has been archived by the owner on Jan 28, 2018. It is now read-only.

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history 
[skip ci]
  • Loading branch information
@itskingori
itskingori committed Nov 3, 2014
1 parent 14d3522 commit bdc55b2
Showing 1 changed file with 48 additions and 36 deletions.
84 changes: 48 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ In case you were wondering:
The gem should be [up on RubyGems.org][5], the [CHANGELOG here][7] and [all the
releases listed here][8].

_Ps: Only developed and tested using a Rails app with a Postgres DB._


Installation
------------
Expand All @@ -29,11 +31,12 @@ Add this line to your application's Gemfile:

gem 'annotator-store'

And then execute:
And then from the app root execute:

$ bundle install

Run the migrations to create the tables to store the annotations:
Configure your database credentials in `config/database.yml` and then run the
migrations to create the tables to store the annotations:

$ rake annotator_store:install:migrations
$ rake db:migrate
Expand All @@ -43,13 +46,15 @@ Then mount it in `config/routes.rb`:
# Configures store endpoint in your app
mount AnnotatorStore::Engine, at: '/annotator_store'

Now it should be ready for use. All the endpoints will be available at `http://0.0.0.0:3000/annotator_store`.
Now it should be ready for use. All the endpoints will be available at
`http://0.0.0.0:3000/annotator_store` in your app.


Annotation Format
-----------------

An annotation is a JSON document that contains a number of fields describing the position and content of an annotation within a specified document:
An annotation is a JSON document that contains a number of fields describing the
position and content of an annotation within a specified document:

{
"id": "39fc339cf058bd22176771b3e3187329", # unique id (added by backend)
Expand All @@ -75,13 +80,13 @@ API Endpoints

### Root

| Method | Path | Returns |
| ------ | ---- | ------------------------------------------------------- |
| GET | / | Object containing store metadata, including API version |
| Method | Path | Returns |
| ------ | ---- | ------------------------------------------------------------------------ |
| GET | / | `200 OK` with an object containing store metadata, including API version |

Returns (example):

$ curl http://example.com/annotator_store
$ curl http://example.com/annotator_store
{
"name": "Annotator Store API",
"version": "2.0.0",
Expand Down Expand Up @@ -119,18 +124,18 @@ Returns (example):

### Create

| Method | Path | Returns |
| ------- | ------------ | --------------------------------------------------------- |
| POST | /annotations | `303 SEE OTHER` redirect to the appropriate read endpoint |
| Method | Path | Returns |
| ------- | ------------ | --------------------------------------------------------------------- |
| POST | /annotations | `200 OK` with location in header set to the appropriate read endpoint |

Receives an annotation object in the proper annotation format, sent with `Content-Type: application/json`.


### Read

| Method | Path | Returns |
| ------ | ---------------- | -------------------- |
| GET | /annotations/:id | An annotation object |
| Method | Path | Returns |
| ------ | ---------------- | ---------------------------------- |
| GET | /annotations/:id | `200 OK` with an annotation object |

Returns (example):

Expand All @@ -144,18 +149,18 @@ Returns (example):

### Update

| Method | Path | Returns |
| ---------- | ---------------- | --------------------------------------------------------- |
| PUT/PATCH | /annotations/:id | `303 SEE OTHER` redirect to the appropriate read endpoint |
| Method | Path | Returns |
| ---------- | ---------------- | --------------------------------------------------------------------- |
| PUT/PATCH | /annotations/:id | `200 OK` with location in header set to the appropriate read endpoint |

Receives attributes in the proper annotation format, sent with `Content-Type: application/json`.


### Delete

| Method | Path | Returns |
| ---------- | ---------------- | ---------------------------------------------- |
| DELETE | /annotations/:id | `204 NO CONTENT`, and – obviously – no content |
| Method | Path | Returns |
| ---------- | ---------------- | ------------------------------------------ |
| DELETE | /annotations/:id | `204 NO CONTENT` and obviously, no content |


### Search
Expand All @@ -164,9 +169,14 @@ Receives attributes in the proper annotation format, sent with `Content-Type: ap
| ------ | -------- | ------------------------------------------------------- |
| GET | /search | An object with total and rows fields |

Total is an integer denoting the total number of annotations matched by the search, while rows is a list containing what might be a subset of these annotations.
_Total_ is an integer denoting the total number of annotations matched by the
search, while _rows_ is a list containing what might be a subset of these
annotations.

If implemented, this endpoint should also support the `limit` and `offset` query
parameters for paging through results.

If implemented, this method should also support the `limit` and `offset` query parameters for paging through results.
_Ps: Pagination with limit and offset not yet implemented. See [issue #1][15]._

Returns (example):

Expand All @@ -193,20 +203,21 @@ typical Rails testing environment, allowing for unit, functional and integration
tests.

The current dummy app uses Rails 4.1.6 and Postgres as a store. It's my hope
that the gem works at least for all Rails versions `>= 4.0.0` and other data
stores that Rails supports like SQLite, MySQL, MongoDB etc ... I guess we'll see
how it goes.
that the gem works at least for all Rails versions `>= 4.0.0` (I don't see why
not) and other data stores that Rails supports like SQLite, MySQL, MongoDB etc
(since Rails uses an ORM) ... I guess we'll see how it goes.

You can see what the engine has so far by running `rails server` in `spec/dummy`
and then browse to `http://localhost:3000/`.
and then browse to `http://0.0.0.0:3000/`.


Testing
-------

You may extend the dummy application by generating controllers, models or views
from within the directory (`spec/dummy`), and then use those to test our engine.
Use the rspec command to run your specs.
from within the directory (`spec/dummy`), and then use those to test our engine
(I've done this already but feel free to add). Then use the rspec command to run
your specs.


```
Expand All @@ -219,11 +230,12 @@ $ bundle exec rspec
=> Run only model specs example ...
$ bundle exec rspec spec/models
=> Run only specs for AnnotationsController ...
=> Run only specs for AnnotatorStore::AnnotationsController ...
$ bundle exec rspec spec/controllers/annotations_controller_spec.rb
```

Testing is also [automated on Travis-CI][13].
Automated tests are configured and set up to [run on Travis-CI][13]. Any push
or pull request will be built.


Versioning
Expand All @@ -240,8 +252,8 @@ changes as per [Semantic Versioning 2.0.0][semver].
Contributing
------------

Want to contribute to the code? First, have a look at the guide in the [CONTRIBUTING.md][9]
file for the workflow.
Want to contribute to the code? First, have a look at the guide in the
[CONTRIBUTING.md][9] file for the workflow.

Then, here's some Annotator documentation to help you get up to speed:

Expand All @@ -256,13 +268,12 @@ Any code contributors should be [listed here][12].
License
-------

[King'ori J. Maina][2] © 2014. The MIT License bundled therein is a
permissive license that is short and to the point. It lets people do anything
they want as long as they provide attribution and waive liability.
[King'ori J. Maina][2] © 2014. The MIT License bundled therein is a permissive
license that is short and to the point. It lets people do anything they want as
long as they provide attribution and waive liability.


[annotator]: http://annotatorjs.org/

[semver]: http://semver.org

[1]: http://docs.annotatorjs.org/en/latest/hacking/plugin-development.html
Expand All @@ -279,3 +290,4 @@ they want as long as they provide attribution and waive liability.
[12]: https://github.com/itsmrwave/annotator-store/graphs/contributors
[13]: https://travis-ci.org/itsmrwave/annotator-store
[14]: https://github.com/itsmrwave/annotator-store-demo
[15]: https://github.com/itsmrwave/annotator-store/issues/1

0 comments on commit bdc55b2

Please sign in to comment.