From 8b34ba1277ba3ebcd3413dbc6c80c923704d574b Mon Sep 17 00:00:00 2001 From: d2kagw Date: Sun, 7 Jun 2015 19:17:16 +1000 Subject: [PATCH 01/88] removed forked junk --- CHANGELOG.md | 30 ------------ CONTRIBUTING.md | 9 ---- README.md | 121 ++---------------------------------------------- 3 files changed, 3 insertions(+), 157 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8adca156616..00000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,30 +0,0 @@ -# Changelog - -## Version 1.1 - -*July 27th, 2014* - -**Fixes:** - -- Finally, a fix for the redcarpet upgrade bug - -## Version 1.0 - -*July 2, 2014* - -[View Issues](https://github.com/tripit/slate/issues?milestone=1&state=closed) - -**Features:** - -- Responsive designs for phones and tablets -- Started tagging versions - -**Fixes:** - -- Fixed 'unrecognized expression' error -- Fixed #undefined hash bug -- Fixed bug where the current language tab would be unselected -- Fixed bug where tocify wouldn't highlight the current section while searching -- Fixed bug where ids of header tags would have special characters that caused problems -- Updated layout so that pages with disabled search wouldn't load search.js -- Cleaned up Javascript diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index b04fc955ca5..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,9 +0,0 @@ -# Contributing to Slate - -Thanks for contributing to Slate! A couple of quick guidelines for submitting PRs: - -- Please point your pull requests at the `dev` branch, and keep your commit messages clear and informative. -- Please make sure your contributions work in the most recent version of Chrome, Firefox, and IE. -- If you're implementing a new feature, even if it's relatively small, it's nice to open an issue before you start so that others know what you're working on and can help make sure you're on the right track. - -Thanks again! Happy coding. \ No newline at end of file diff --git a/README.md b/README.md index 21ec87edac2..a68a2bf68b9 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,4 @@ -Slate -======== +The home of our various API, Gem and other public documentation. +That's right, **PUBLIC**. -[![Build Status](https://travis-ci.org/tripit/slate.svg?branch=master)](https://travis-ci.org/tripit/slate) [![Dependency Status](https://gemnasium.com/tripit/slate.png)](https://gemnasium.com/tripit/slate) - -Slate helps you create beautiful API documentation. Think of it as an intelligent, responsive documentation template for your API. - -Screenshot of Example Documentation created with Slate - -*The example above was created with Slate. Check it out at [tripit.github.io/slate](http://tripit.github.io/slate).* - -Features ------------- - -* **Clean, intuitive design** — with Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by [Stripe's](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. Slate is responsive, so it looks great on tablets, phones, and even print. - -* **Everything on a single page** — gone are the days where your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so linking to a particular point in the documentation is still natural and easy. - -* **Slate is just Markdown** — when you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. Everything is written in Markdown — even the code samples are just Markdown code blocks! - -* **Write code samples in multiple languages** — if your API has bindings in multiple programming languages, you easily put in tabs to switch between them. In your document, you'll distinguish different languages by specifying the language name at the top of each code block, just like with Github Flavored Markdown! - -* **Out-of-the-box syntax highlighting** for [almost 60 languages](http://rouge.jayferd.us/demo), no configuration required. - -* **Automatic, smoothly scrolling table of contents** on the far left of the page. As you scroll, it displays your current position in the document. It's fast, too. We're using Slate at TripIt to build documentation for our new API, where our table of contents has over 180 entries. We've made sure that the performance remains excellent, even for larger documents. - -* **Let your users update your documentation for you** — by default, your Slate-generated documentation is hosted in a public Github repository. Not only does this mean you get free hosting for your docs with Github Pages, but it also makes it's simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to, you're welcome to not use Github and host your docs elsewhere! - -Getting starting with Slate is super easy! Simply fork this repository, and then follow the instructions below. Or, if you'd like to check out what Slate is capable of, take a look at the [sample docs](http://tripit.github.io/slate). - - - -Getting Started with Slate ------------------------------- - -### Prerequisites - -You're going to need: - - - **Linux or OS X** — Windows may work, but is unsupported. - - **Ruby, version 1.9.3 or newer** - - **Bundler** — If Ruby is already installed, but the `bundle` command doesn't work, just run `gem install bundler` in a terminal. - -### Getting Set Up - - 1. Fork this repository on Github. - 2. Clone *your forked repository* (not our original one) to your hard drive with `git clone https://github.com/YOURUSERNAME/slate.git` - 3. `cd slate` - 4. Install all dependencies: `bundle install` - 5. Start the test server: `bundle exec middleman server` - -Or use the included Dockerfile! (must install Docker first) - -```shell -docker build -t slate . -docker run -d -p 4567:4567 slate -``` - -You can now see the docs at . Whoa! That was fast! - -*Note: if you're using the Docker setup on OSX, the docs will be -availalable at the output of `boot2docker ip` instead of `localhost:4567`.* - -Now that Slate is all set up your machine, you'll probably want to learn more about [editing Slate markdown](https://github.com/tripit/slate/wiki/Markdown-Syntax), or [how to publish your docs](https://github.com/tripit/slate/wiki/Deploying-Slate). - -Examples of Slate in the Wild ---------------------------------- - -* [Travis-CI's API docs](http://docs.travis-ci.com/api/) -* [Mozilla's localForage docs](http://mozilla.github.io/localForage/) -* [Mozilla Recroom](http://mozilla.github.io/recroom/) -* [ChaiOne Gameplan API docs](http://chaione.github.io/gameplanb2b/#introduction) -* [Drcaban's Build a Quine tutorial](http://drcabana.github.io/build-a-quine/#introduction) -* [PricePlow API docs](https://www.priceplow.com/api/documentation) -* [Emerging Threats API docs](http://apidocs.emergingthreats.net/) -* [Appium docs](http://appium.io/slate/en/master) -* [Golazon Developer](http://developer.golazon.com) -* [Dwolla API docs](https://docs.dwolla.com/) -* [RozpisyZapasu API docs](http://www.rozpisyzapasu.cz/dev/api/) -* [Codestar Framework Docs](http://codestarframework.com/documentation/) -* [Buddycloud API](http://buddycloud.com/api) -* [Crafty Clicks API](https://craftyclicks.co.uk/api/) -* [Paracel API Reference](http://paracel.io/docs/api_reference.html) -* [Switch Payments Documentation](http://switchpayments.com/docs/) & [API](http://switchpayments.com/developers/) -* [Coinbase API Reference](https://developers.coinbase.com/api) -* [Whispir.io API](https://whispir.github.io/api) -* [NASA API](https://data.nasa.gov/developer/external/planetary/) -* [CardPay API](https://developers.cardpay.com/) -* [IBM Cloudant](https://docs-testb.cloudant.com/content-review/_design/couchapp/index.html) -* [Bitrix basis components](http://bbc.bitrix.expert/) - -(Feel free to add your site to this list in a pull request!) - -Need Help? Found a bug? --------------------- - -Just [submit a issue](https://github.com/tripit/slate/issues) to the Slate Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes. - - -Contributors --------------------- - -Slate was built by [Robert Lord](http://lord.io) while at [TripIt](http://tripit.com). - -Thanks to the following people who have submitted major pull requests: - -- [@chrissrogers](https://github.com/chrissrogers) -- [@bootstraponline](https://github.com/bootstraponline) -- [@realityking](https://github.com/realityking) - -Also, thanks to [Sauce Labs](http://saucelabs.com) for helping sponsor the project. - -Special Thanks --------------------- -- [Middleman](https://github.com/middleman/middleman) -- [jquery.tocify.js](https://github.com/gfranko/jquery.tocify.js) -- [middleman-syntax](https://github.com/middleman/middleman-syntax) -- [middleman-gh-pages](https://github.com/neo/middleman-gh-pages) -- [Font Awesome](http://fortawesome.github.io/Font-Awesome/) +Whatever is here is publicly available at http://developer.lexer.io. From 7de905473d1d3a1b1cf417cc41c80d4805d352e3 Mon Sep 17 00:00:00 2001 From: d2kagw Date: Sun, 7 Jun 2015 19:17:27 +1000 Subject: [PATCH 02/88] initial content update much work to do --- source/includes/_errors.md | 20 ---- source/includes/_events.md | 5 + source/includes/_identities.md | 10 ++ source/includes/_publish.md | 5 + source/index.md | 163 ++++++++++----------------------- 5 files changed, 67 insertions(+), 136 deletions(-) delete mode 100644 source/includes/_errors.md create mode 100644 source/includes/_events.md create mode 100644 source/includes/_identities.md create mode 100644 source/includes/_publish.md diff --git a/source/includes/_errors.md b/source/includes/_errors.md deleted file mode 100644 index 56cffb34d22..00000000000 --- a/source/includes/_errors.md +++ /dev/null @@ -1,20 +0,0 @@ -# Errors - - - -The Kittn API uses the following error codes: - - -Error Code | Meaning ----------- | ------- -400 | Bad Request -- Your request sucks -401 | Unauthorized -- Your API key is wrong -403 | Forbidden -- The kitten requested is hidden for administrators only -404 | Not Found -- The specified kitten could not be found -405 | Method Not Allowed -- You tried to access a kitten with an invalid method -406 | Not Acceptable -- You requested a format that isn't json -410 | Gone -- The kitten requested has been removed from our servers -418 | I'm a teapot -429 | Too Many Requests -- You're requesting too many kittens! Slow down! -500 | Internal Server Error -- We had a problem with our server. Try again later. -503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later. diff --git a/source/includes/_events.md b/source/includes/_events.md new file mode 100644 index 00000000000..e8d69de15d9 --- /dev/null +++ b/source/includes/_events.md @@ -0,0 +1,5 @@ +# Events API + +TODO - Write Events API documentation + +cURL + Ruby Gem diff --git a/source/includes/_identities.md b/source/includes/_identities.md new file mode 100644 index 00000000000..2ad09a00f1f --- /dev/null +++ b/source/includes/_identities.md @@ -0,0 +1,10 @@ +# Identities API + +TODO - Write Identities API documentation + +cURL + Ruby Gem + +## Namespaces + +TODO + diff --git a/source/includes/_publish.md b/source/includes/_publish.md new file mode 100644 index 00000000000..d9c856c2375 --- /dev/null +++ b/source/includes/_publish.md @@ -0,0 +1,5 @@ +# Publish API + +TODO - Write Publish API documentation + +cURL + Ruby Gem diff --git a/source/index.md b/source/index.md index ed5f6d63d0e..c634858534f 100644 --- a/source/index.md +++ b/source/index.md @@ -1,168 +1,99 @@ --- -title: API Reference +title: Lexer API Reference language_tabs: - shell - ruby - - python toc_footers: - - Sign Up for a Developer Key + - Find out more about Lexer - Documentation Powered by Slate includes: - - errors + - identities + - events + - publish search: true --- # Introduction -Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database. +Welcome to the Lexer API. -We have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. +We offer three APIs to our clients: -This example API documentation page was created with [Slate](http://github.com/tripit/slate). Feel free to edit it and use it as a base for your own API's documentation. +- Identities: Allowing clients to Contribute and Consume Identity data from the Lexer platform. +- Events: Allowing clients to push Event data to the Lexer platform. +- Publish: Allowing clients to extract and publish search results and other insights from the Lexer platform. -# Authentication +To access any of the APIs you will require `access tokens` which may have been provided to you. Please [contact support](mailto:support@lexer.io) if you have not received these. -> To authorize, use this code: +All our API's communicate via HTTPS using RESTful and [JSON](http://json.org/) data. We offer Ruby Gems for most of our APIs. -```ruby -require 'kittn' - -api = Kittn::APIClient.authorize!('meowmeowmeow') -``` -```python -import kittn +# Fair Use -api = kittn.authorize('meowmeowmeow') -``` - -```shell -# With shell, you can just pass the correct header with each request -curl "api_endpoint_here" - -H "Authorization: meowmeowmeow" -``` +Lexer operates a fair use policy on all it's APIs. -> Make sure to replace `meowmeowmeow` with your API key. +Refer to your projects terms of service for details on rate limiting, performance limitations, maintenance windows and SLAs. -Kittn uses API keys to allow access to the API. You can register a new Kittn API key at our [developer portal](http://example.com/developers). +For further details please [contact support](mailto:support@lexer.io). -Kittn expects for the API key to be included in all API requests to the server in a header that looks like the following: -`Authorization: meowmeowmeow` +# Access Tokens - - -# Kittens - -## Get All Kittens - -```ruby -require 'kittn' - -api = Kittn::APIClient.authorize!('meowmeowmeow') -api.kittens.get -``` - -```python -import kittn - -api = kittn.authorize('meowmeowmeow') -api.kittens.get() -``` +> Tokens are used as part of the JSON request body: ```shell -curl "http://example.com/api/kittens" - -H "Authorization: meowmeowmeow" +curl -X POST -H "Content-Type: application/json" --data '{"api_token":"lexer-api-token","consumer_token":"lexer-consumer-token","contributor_token":"lexer-contrib-token", ... }' https://identity.apis.lexer.io ``` -> The above command returns JSON structured like this: - -```json -[ - { - "id": 1, - "name": "Fluffums", - "breed": "calico", - "fluffiness": 6, - "cuteness": 7 - }, - { - "id": 2, - "name": "Isis", - "breed": "unknown", - "fluffiness": 5, - "cuteness": 10 - } -] +```ruby +# Using the `lexer-identity` Gem: +Lexer::Identity.configure do |config| + config.api_token = 'lexer-api-token' + config.consumer_token = 'lexer-consumer-token' + config.contributor_token = 'lexer-contrib-token' +end ``` -This endpoint retrieves all kittens. - -### HTTP Request - -`GET http://example.com/kittens` +> Make sure to replace the tokens with those provided. -### Query Parameters +Lexer protects it's APIs through access tokens. -Parameter | Default | Description ---------- | ------- | ----------- -include_cats | false | If set to true, the result will also include cats. -available | true | If set to false, the result will include kittens that have already been adopted. +In all cases a unique token should be generated for each party who should communicate with the APIs. - +Lexer can dispose of and recreate API tokens whenever required should a token be feared to have been leaked or a party should no longer require access to the APIs. -## Get a Specific Kitten +There are at least two of three possible tokens which you will need to communicate with the APIs: -```ruby -require 'kittn' +* API Token + Consumer Token: Read only access to Lexer APIs +* API + Contributor Tokens: Write only access to Lexer APIs +* API + Consumer + Contributor Tokens: Read and Write access to Lexer APIs -api = Kittn::APIClient.authorize!('meowmeowmeow') -api.kittens.get(2) -``` +## API Token -```python -import kittn +An API token is required to communicate with our API. -api = kittn.authorize('meowmeowmeow') -api.kittens.get(2) -``` +All requests require an API token and a unique token will be provided to each party who wishes to communicate with the Lexer APIs. -```shell -curl "http://example.com/api/kittens/3" - -H "Authorization: meowmeowmeow" -``` +An API token alone offers no access to the Lexer APIs you need at lease a Consumer or Contributor (or one of each) tokens to make a valid request. -> The above command returns JSON structured like this: +## Consumer Token -```json -{ - "id": 2, - "name": "Isis", - "breed": "unknown", - "fluffiness": 5, - "cuteness": 10 -} -``` +A Consumer Token is supplied if the party requires `read` access to the Lexer APIs. -This endpoint retrieves a specific kitten. +When created a Consumer Token is locked to a specific namespace only granting that token access to a specific dataset. - +A Consumer token does not allow a party to `write` data to a Lexer API. +For that a Contributor token is required. -### HTTP Request +## Contributor Token -`GET http://example.com/kittens/` +A Contributor token is supplied if the party requires `write` access to the Lexer APIs. -### URL Parameters +When created a Contributor Token is locked to a specific namespace only granting that token access to a specific dataset. -Parameter | Description ---------- | ----------- -ID | The ID of the cat to retrieve +All requests made to the Lexer API will have limited responses unless a Contributor token (`write` access) is paired with a Consumer token (`read` access). From 7860e9dcd8cf37fcc77c8494a2ff0af87bcb6a15 Mon Sep 17 00:00:00 2001 From: d2kagw Date: Tue, 9 Jun 2015 13:05:36 +1000 Subject: [PATCH 03/88] updated help --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index a68a2bf68b9..b0b9faaea8e 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,18 @@ The home of our various API, Gem and other public documentation. That's right, **PUBLIC**. Whatever is here is publicly available at http://developer.lexer.io. + +## How to run + + # run a server on http://localhost:7890 + bundle exec middleman server --port=7890 + +## How to build + + # build the documentation for deployment + bundle exec rake build + +Builds are written to source and that folder is to be deployed. +No special tech required, it's a static site. + + From e6471f8b7b30ba2dc455aaba3c8af2a9472ffa41 Mon Sep 17 00:00:00 2001 From: d2kagw Date: Tue, 9 Jun 2015 13:08:54 +1000 Subject: [PATCH 04/88] got the instructions wrong --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index b0b9faaea8e..f941067fbc5 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,5 @@ Whatever is here is publicly available at http://developer.lexer.io. # build the documentation for deployment bundle exec rake build -Builds are written to source and that folder is to be deployed. +Builds are written to a "build" and that folder is to be deployed - this is not checked in. No special tech required, it's a static site. - - From b761ec88ee138f3a5dda8c4a2d9d73c49c262ac5 Mon Sep 17 00:00:00 2001 From: Matt Michalowski Date: Thu, 18 Jun 2015 18:30:32 +1000 Subject: [PATCH 05/88] WIP --- Gemfile.lock | 25 +++++++------ source/includes/_identities.md | 27 +++++++++++--- source/index.md | 66 +++++++++++++++++----------------- 3 files changed, 70 insertions(+), 48 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index e3931cd63af..7c1d8c56a83 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ GEM remote: http://rubygems.org/ specs: - activesupport (4.1.10) + activesupport (4.1.11) i18n (~> 0.6, >= 0.6.9) json (~> 1.7, >= 1.7.7) minitest (~> 5.1) @@ -36,25 +36,25 @@ GEM hooks (0.4.0) uber (~> 0.0.4) i18n (0.7.0) - json (1.8.2) + json (1.8.3) kramdown (1.7.0) libv8 (3.16.14.7) - listen (2.10.0) + listen (2.10.1) celluloid (~> 0.16.0) rb-fsevent (>= 0.9.3) rb-inotify (>= 0.9) - middleman (3.3.11) + middleman (3.3.12) coffee-script (~> 2.2) compass (>= 1.0.0, < 2.0.0) compass-import-once (= 1.0.5) execjs (~> 2.0) haml (>= 4.0.5) kramdown (~> 1.2) - middleman-core (= 3.3.11) + middleman-core (= 3.3.12) middleman-sprockets (>= 3.1.2) sass (>= 3.4.0, < 4.0) uglifier (~> 2.5) - middleman-core (3.3.11) + middleman-core (3.3.12) activesupport (~> 4.1.0) bundler (~> 1.1) erubis @@ -76,25 +76,25 @@ GEM middleman-syntax (2.0.0) middleman-core (~> 3.2) rouge (~> 1.0) - minitest (5.6.1) - multi_json (1.11.0) + minitest (5.7.0) + multi_json (1.11.1) padrino-helpers (0.12.5) i18n (~> 0.6, >= 0.6.7) padrino-support (= 0.12.5) tilt (~> 1.4.1) padrino-support (0.12.5) activesupport (>= 3.1) - rack (1.6.0) + rack (1.6.2) rack-test (0.6.3) rack (>= 1.0) rake (10.4.2) - rb-fsevent (0.9.4) + rb-fsevent (0.9.5) rb-inotify (0.9.5) ffi (>= 0.5.0) redcarpet (3.2.3) ref (1.0.5) rouge (1.8.0) - sass (3.4.13) + sass (3.4.14) sprockets (2.12.3) hike (~> 1.2) multi_json (~> 1.0) @@ -131,3 +131,6 @@ DEPENDENCIES redcarpet (~> 3.2.2) rouge (~> 1.8.0) therubyracer (~> 0.12.1) + +BUNDLED WITH + 1.10.4 diff --git a/source/includes/_identities.md b/source/includes/_identities.md index 2ad09a00f1f..c7d6cce5658 100644 --- a/source/includes/_identities.md +++ b/source/includes/_identities.md @@ -1,10 +1,29 @@ # Identities API -TODO - Write Identities API documentation +TODO - identities spiel. -cURL + Ruby Gem +### ROOT Endpoint -## Namespaces +All access to the Lexer Identity API is performed via a single root endpoint. The correct behavior. All input must be securely `POST`ed in JSON format to this URL: -TODO +`https://identity.lexer.io/identity` +### Namespaces + +TODO - namespace stuff. + + +## Contributions + +The presence of a valid contributor_token in the input payload instructs the Identity API to create or update a unique identity. Generally, two or more _linkage attributes_, or `links`, that are unique to an identity, must be provided in order for an identity to be created. + +### Links + +### Attributes + +### Updates + +## Consumption + + +## Errors diff --git a/source/index.md b/source/index.md index c634858534f..db423c5eaa2 100644 --- a/source/index.md +++ b/source/index.md @@ -7,36 +7,30 @@ language_tabs: toc_footers: - Find out more about Lexer - - Documentation Powered by Slate + - (Docs Powered by Slate) includes: - identities - - events - - publish search: true --- # Introduction -Welcome to the Lexer API. +Welcome to the Lexer API documentation. -We offer three APIs to our clients: +We currently offer the following APIs to our clients: - Identities: Allowing clients to Contribute and Consume Identity data from the Lexer platform. -- Events: Allowing clients to push Event data to the Lexer platform. -- Publish: Allowing clients to extract and publish search results and other insights from the Lexer platform. -To access any of the APIs you will require `access tokens` which may have been provided to you. Please [contact support](mailto:support@lexer.io) if you have not received these. +All of our APIs communicate via HTTPS and JSON data. We offer Ruby Gems for most of our APIs. -All our API's communicate via HTTPS using RESTful and [JSON](http://json.org/) data. We offer Ruby Gems for most of our APIs. +## Fair Use -# Fair Use +Lexer operates a fair use policy on all of its APIs. -Lexer operates a fair use policy on all it's APIs. - -Refer to your projects terms of service for details on rate limiting, performance limitations, maintenance windows and SLAs. +Refer to your project's terms of service for details on rate limiting, performance limitations, maintenance windows and SLAs. For further details please [contact support](mailto:support@lexer.io). @@ -46,54 +40,60 @@ For further details please [contact support](mailto:support@lexer.io). > Tokens are used as part of the JSON request body: ```shell -curl -X POST -H "Content-Type: application/json" --data '{"api_token":"lexer-api-token","consumer_token":"lexer-consumer-token","contributor_token":"lexer-contrib-token", ... }' https://identity.apis.lexer.io +curl https://identity.lexer.io/identity \ + -XPOST \ + -H "Content-Type: application/json" \ + -d ' +{ + "api_token": "lexer-api-token", + "consumer_token": "lexer-consumer-token", + "contributor_token":"lexer-contrib-token" +}' ``` ```ruby -# Using the `lexer-identity` Gem: +require 'lexer' + Lexer::Identity.configure do |config| config.api_token = 'lexer-api-token' - config.consumer_token = 'lexer-consumer-token' config.contributor_token = 'lexer-contrib-token' + config.consumer_token = 'lexer-consumer-token' end ``` > Make sure to replace the tokens with those provided. -Lexer protects it's APIs through access tokens. - -In all cases a unique token should be generated for each party who should communicate with the APIs. - -Lexer can dispose of and recreate API tokens whenever required should a token be feared to have been leaked or a party should no longer require access to the APIs. +To access any Lexer API you will require unique `access tokens` which will be provided to you. Please [contact support](mailto:support@lexer.io) if you have not received these. There are at least two of three possible tokens which you will need to communicate with the APIs: * API Token + Consumer Token: Read only access to Lexer APIs * API + Contributor Tokens: Write only access to Lexer APIs -* API + Consumer + Contributor Tokens: Read and Write access to Lexer APIs +* API + Consumer + Contributor Tokens: Read _and_ Write access to Lexer APIs -## API Token +### API Token An API token is required to communicate with our API. All requests require an API token and a unique token will be provided to each party who wishes to communicate with the Lexer APIs. -An API token alone offers no access to the Lexer APIs you need at lease a Consumer or Contributor (or one of each) tokens to make a valid request. +An API token alone offers no access to the Lexer APIs. You need at least a Consumer or Contributor token to make a valid request. Both a Consumer and Contributor token can be provided in a single request payload for simultaneous read/write access. -## Consumer Token +### Consumer Token -A Consumer Token is supplied if the party requires `read` access to the Lexer APIs. +A Consumer Token is supplied if the party requires **read** access to the Lexer APIs. -When created a Consumer Token is locked to a specific namespace only granting that token access to a specific dataset. +When created, a Consumer Token is locked to a specific namespace only granting that token access to a specific dataset. -A Consumer token does not allow a party to `write` data to a Lexer API. -For that a Contributor token is required. +A Consumer token does not allow a party to **write** data to a Lexer API. For that a Contributor token is required. -## Contributor Token +### Contributor Token -A Contributor token is supplied if the party requires `write` access to the Lexer APIs. +A Contributor token is supplied if the party requires **write** access to the Lexer APIs. -When created a Contributor Token is locked to a specific namespace only granting that token access to a specific dataset. +When created, a Contributor Token is locked to a specific namespace only granting that token access to a specific dataset. -All requests made to the Lexer API will have limited responses unless a Contributor token (`write` access) is paired with a Consumer token (`read` access). + From fc1d168111826ee4232f6347836560ab4529f5d1 Mon Sep 17 00:00:00 2001 From: Matt Michalowski Date: Fri, 19 Jun 2015 18:26:57 +1000 Subject: [PATCH 06/88] fix sentence --- source/includes/_identities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/_identities.md b/source/includes/_identities.md index c7d6cce5658..70716a122ca 100644 --- a/source/includes/_identities.md +++ b/source/includes/_identities.md @@ -4,9 +4,9 @@ TODO - identities spiel. ### ROOT Endpoint -All access to the Lexer Identity API is performed via a single root endpoint. The correct behavior. All input must be securely `POST`ed in JSON format to this URL: +All access to the Lexer Identity API is performed via a single root endpoint. The correct behavior of the API is determined by various input payload contexts. All input must be securely `POST`ed in JSON format to this URL: -`https://identity.lexer.io/identity` +`https://identity.api.lexer.io/` ### Namespaces From feae218cd56cd1948d6ff12e1df4c9cf61de40f3 Mon Sep 17 00:00:00 2001 From: d2kagw Date: Mon, 22 Jun 2015 16:04:41 +1000 Subject: [PATCH 07/88] WIP of identities documentation --- source/images/logo.png | Bin 3507 -> 13614 bytes source/includes/_identities.md | 121 +++++++++++++++++++++++++++-- source/index.md | 41 ++++++---- source/stylesheets/_variables.scss | 59 +++++++------- source/stylesheets/screen.css.scss | 112 +++++++++++++------------- 5 files changed, 227 insertions(+), 106 deletions(-) diff --git a/source/images/logo.png b/source/images/logo.png index fa1f13da8193dacca747df56cc1f7bb0bc111a7e..8a9ee0a4b02a1990599cb9fc719669e0682cdb70 100644 GIT binary patch literal 13614 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 diff --git a/source/includes/_identities.md b/source/includes/_identities.md index 70716a122ca..92835e048ee 100644 --- a/source/includes/_identities.md +++ b/source/includes/_identities.md @@ -1,21 +1,125 @@ -# Identities API +# Identity API -TODO - identities spiel. +The Lexer Identity API allows clients and their partners to read and write Identity information to [Lexer Identify](http://lexer.io). + +For details on the capability and project specific implementation of [Lexer Identify](http://lexer.io) please contact support at [support@lexer.io](mailto:support@lexer.io). + +An Identity is a person, brand, place or thing. +Each Identity has thousands of attributes which are generated and updated in real-time through the Lexer Identify platform. + +Each Identity is made up of: + +- **Links**: Highly personal and unique attributes such as Email address, Mobile number, Twitter handle, Facebook ID, etc. These attributes belong to a single identity. +- **Attributes**: An identity could contain thousands of attributes - each one defining their behaviour, facts and engagements. Examples are `age`, `gender`, `favourite food`, `spouse`, etc. + +Clients can use the Lexer Identify platform to gather real-time insights on their customers, prospects and competitors by: + +1. Linking their proprietary data with a Lexer Identity +2. Contributing additional information to enrich the Lexer Identity +3. Consume the Identities attributes into internal or 3rd party platforms for activation + +All this is done within the Identity API. + +## Configuration ### ROOT Endpoint -All access to the Lexer Identity API is performed via a single root endpoint. The correct behavior of the API is determined by various input payload contexts. All input must be securely `POST`ed in JSON format to this URL: +```text +https://identity.api.lexer.io/ +``` -`https://identity.api.lexer.io/` +All access to the Lexer Identity API is performed via a single root endpoint. The correct behaviour of the API is determined by various input payload contexts. All input must be securely `POST`ed in JSON format to this URL: -### Namespaces +### Payload + +```json +{ + "api_token": "abc-123-...", + "consumer_token": "qwe-345-...", + "contributor_token": "ert-678-...", + "id": "987-mnb-...", + "links": { + "email": "joe.blog@mybrand.com", + "mobile": "+61404555444" + }, + "attributes": { + "com.mybrand.age": 32, + "com.mybrand.car.colour": "red" + } +} +``` + +All input must be securely `POST`ed in JSON format to the [ROOT endpoint](#root-endpoint) and must contain the following keys: + +Key | Required | Description +----- | --- | ---- +api_token | Yes | The api token as provided by Lexer. +consumer_token | No | The consumer token as provided by Lexer. +contributor_token | No | The contributor token as provided by Lexer. +id | No | A Lexer ID if one is known. Is used over `links` if provided. +links | No | A hash of [linkage attributes](#links) unique to the Identity. Only required if an `id` is not present. +attributes | No | A hash of [attributes](#attributes) to be written to the Identity. Only required if a `contributior_token` is present. + + +### Tokens + +```shell +curl https://identity.api.lexer.io/identity \ + -XPOST \ + -H "Content-Type: application/json" \ + -d ‘ +{ + "api_token": "your-api-token", + "consumer_token": "your-consumer-token", + "contributor_token": "your-contrib-token" +}’ +``` + +```ruby +curl https://identity.api.lexer.io/identity \ + -XPOST \ + -H "Content-Type: application/json" \ + -d ‘ +{ + "api_token": "your-api-token", + "consumer_token": "your-consumer-token", + "contributor_token": "your-contrib-token" +}’ +``` -TODO - namespace stuff. +As outlined in [Access Tokens](#access-tokens) a set of tokens are required for all communication with the API. + +An API token along with a Contributor and/or a Consumer token is required. + +You can validate your tokens by making a `curl` request to the API. + +A `403: Forbidden` will be returned if your tokens are invalid. + +Contact [support@lexer.io](mailto:support@lexer.io) if you require assistance. ## Contributions -The presence of a valid contributor_token in the input payload instructs the Identity API to create or update a unique identity. Generally, two or more _linkage attributes_, or `links`, that are unique to an identity, must be provided in order for an identity to be created. +The presence of a valid `contributor_token` in the input payload instructs the Identity API to create or update a unique identity. Generally, two or more _linkage attributes_, or `links`, that are unique to an identity, must be provided in order for an identity to be created. + +### Namespaces + +Each _Consumer Token_ and _Contributor Token_ is bound to a particular namespace. + +A namespace is commonly defined as a reverse domain name. Such as `io.lexer.*`. + +Namespaces are used within the platform to: + +1. **Protect Secure Information**: Tokens can only read from defined namespaces, limiting each parties access to only the attributes permitted. +2. **Enforce Business Policy**: Our clients often have many partners with a complex permission tree. Using namespaces we’re able to allow certain partners to access certain attributes. + +Each attribute on an Identity has a name within the namespace. For example: + +- `io.lexer.age` defines the age of the Identity according to Lexer +- `com.mybrand.age` defines the age of the Identity according to MyBrand +- `com.mybrand.car.colour` defines the colour of the Identities car according to MyBrand + +Please refer to the projects documentation on available namespaces for your implementation. ### Links @@ -25,5 +129,6 @@ The presence of a valid contributor_token in the input payload inst ## Consumption - ## Errors + +# Examples \ No newline at end of file diff --git a/source/index.md b/source/index.md index db423c5eaa2..9e19c0de35c 100644 --- a/source/index.md +++ b/source/index.md @@ -21,10 +21,12 @@ Welcome to the Lexer API documentation. We currently offer the following APIs to our clients: -- Identities: Allowing clients to Contribute and Consume Identity data from the Lexer platform. +- **Identity API**: Allowing clients to Contribute and Consume Identity data from the Lexer platform. All of our APIs communicate via HTTPS and JSON data. We offer Ruby Gems for most of our APIs. +Our _Event_ and _Publish_ API's are currently under development. + ## Fair Use @@ -37,9 +39,9 @@ For further details please [contact support](mailto:support@lexer.io). # Access Tokens -> Tokens are used as part of the JSON request body: - ```shell +# Tokens are used as part of the JSON request body + curl https://identity.lexer.io/identity \ -XPOST \ -H "Content-Type: application/json" \ @@ -47,7 +49,7 @@ curl https://identity.lexer.io/identity \ { "api_token": "lexer-api-token", "consumer_token": "lexer-consumer-token", - "contributor_token":"lexer-contrib-token" + "contributor_token": "lexer-contrib-token" }' ``` @@ -63,35 +65,40 @@ end > Make sure to replace the tokens with those provided. -To access any Lexer API you will require unique `access tokens` which will be provided to you. Please [contact support](mailto:support@lexer.io) if you have not received these. +To access any Lexer API you will require access tokens which will be provided to you. Please [contact support](mailto:support@lexer.io) if you have not received these. There are at least two of three possible tokens which you will need to communicate with the APIs: -* API Token + Consumer Token: Read only access to Lexer APIs -* API + Contributor Tokens: Write only access to Lexer APIs -* API + Consumer + Contributor Tokens: Read _and_ Write access to Lexer APIs +* **API Token + Consumer Token**: Read only access to Lexer APIs +* **API + Contributor Tokens**: Write only access to Lexer APIs +* **API + Consumer + Contributor Tokens**: Read _and_ Write access to Lexer APIs -### API Token + + + +### API Token -All requests require an API token and a unique token will be provided to each party who wishes to communicate with the Lexer APIs. +All requests require an _API token_ which will be provided to each party who require access to the Lexer APIs. -An API token alone offers no access to the Lexer APIs. You need at least a Consumer or Contributor token to make a valid request. Both a Consumer and Contributor token can be provided in a single request payload for simultaneous read/write access. +An _API token_ alone offers no access to the Lexer APIs. You need at least a _Consumer token_ or _Contributor token_ to make a valid request. Both a _Consumer token_ and _Contributor token_ can be provided in a single request payload for simultaneous read/write access. ### Consumer Token -A Consumer Token is supplied if the party requires **read** access to the Lexer APIs. +A _Consumer token_ is supplied if the party requires **read** access to the Lexer APIs. -When created, a Consumer Token is locked to a specific namespace only granting that token access to a specific dataset. +When created, a _Consumer token_ is locked to a specific namespace only granting that token access to a specific dataset. -A Consumer token does not allow a party to **write** data to a Lexer API. For that a Contributor token is required. +A _Consumer token_ does not allow a party to **write** data to a Lexer APIs. For that a _Contributor token_ is required. ### Contributor Token -A Contributor token is supplied if the party requires **write** access to the Lexer APIs. +A _Contributor token_ is supplied if the party requires **write** access to the Lexer APIs. -When created, a Contributor Token is locked to a specific namespace only granting that token access to a specific dataset. +When created, a _Contributor token_ is locked to a specific namespace only granting that token access to a specific dataset.