- Slate: API Documentation Generator
-
- Build Status
- Docker Version
-
Slate helps you create beautiful, intelligent, responsive API documentation.
- -Screenshot of Example Documentation created with Slate
- -The example above was created with Slate. Check it out at slatedocs.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 in print. - -* **Everything on a single page** — Gone are the days when 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 can 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 [over 100 languages](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers), 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 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 use GitHub, you're also welcome to host your docs elsewhere. - -* **RTL Support** Full right-to-left layout for RTL languages such as Arabic, Persian (Farsi), Hebrew etc. - -Getting started with Slate is super easy! Simply press the green "use this template" button above and follow the instructions below. Or, if you'd like to check out what Slate is capable of, take a look at the [sample docs](https://slatedocs.github.io/slate/). - -Getting Started with Slate ------------------------------- - -To get started with Slate, please check out the [Getting Started](https://github.com/slatedocs/slate/wiki#getting-started) -section in our [wiki](https://github.com/slatedocs/slate/wiki). - -We support running Slate in three different ways: -* [Natively](https://github.com/slatedocs/slate/wiki/Using-Slate-Natively) -* [Using Vagrant](https://github.com/slatedocs/slate/wiki/Using-Slate-in-Vagrant) -* [Using Docker](https://github.com/slatedocs/slate/wiki/Using-Slate-in-Docker) - -Companies Using Slate ---------------------------------- - -* [NASA](https://api.nasa.gov) -* [Sony](http://developers.cimediacloud.com) -* [Best Buy](https://bestbuyapis.github.io/api-documentation/) -* [Travis-CI](https://docs.travis-ci.com/api/) -* [Greenhouse](https://developers.greenhouse.io/harvest.html) -* [WooCommerce](http://woocommerce.github.io/woocommerce-rest-api-docs/) -* [Dwolla](https://docs.dwolla.com/) -* [Clearbit](https://clearbit.com/docs) -* [Coinbase](https://developers.coinbase.com/api) -* [Parrot Drones](http://developer.parrot.com/docs/bebop/) -* [CoinAPI](https://docs.coinapi.io/) - -You can view more in [the list on the wiki](https://github.com/slatedocs/slate/wiki/Slate-in-the-Wild). - -Questions? Need Help? Found a bug? --------------------- - -If you've got questions about setup, deploying, special feature implementation in your fork, or just want to chat with the developer, please feel free to [start a thread in our Discussions tab](https://github.com/slatedocs/slate/discussions)! - -Found a bug with upstream Slate? Go ahead and [submit an issue](https://github.com/slatedocs/slate/issues). And, of course, feel free to submit pull requests with bug fixes or changes to the `dev` branch. - -Contributors --------------------- - -Slate was built by [Robert Lord](https://lord.io) while at [TripIt](https://www.tripit.com/). The project is now maintained by [Matthew Peveler](https://github.com/MasterOdin) and [Mike Ralphson](https://github.com/MikeRalphson). - -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) -- [@cvkef](https://github.com/cvkef) - -Also, thanks to [Sauce Labs](http://saucelabs.com) for sponsoring the development of the responsive styles. diff --git a/Vagrantfile b/Vagrantfile deleted file mode 100644 index 8a9981b..0000000 --- a/Vagrantfile +++ /dev/null @@ -1,47 +0,0 @@ -Vagrant.configure(2) do |config| - config.vm.box = "ubuntu/focal64" - config.vm.network :forwarded_port, guest: 4567, host: 4567 - config.vm.provider "virtualbox" do |vb| - vb.memory = "2048" - end - - config.vm.provision "bootstrap", - type: "shell", - inline: <<-shell - # add nodejs v12 repository - curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - - - sudo apt-get update - sudo apt-get install -yq ruby ruby-dev - sudo apt-get install -yq pkg-config build-essential nodejs git libxml2-dev libxslt-dev - sudo apt-get autoremove -yq - gem install --no-document bundler - SHELL - - # add the local user git config to the vm - config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig" - - config.vm.provision "install", - type: "shell", - privileged: false, - inline: <<-shell - echo "==============================================" - echo "Installing app dependencies" - cd /vagrant - sudo gem install bundler -v "$(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -n 1)" - bundle config build.nokogiri --use-system-libraries - bundle install - SHELL - - config.vm.provision "run", - type: "shell", - privileged: false, - run: "always", - inline: <<-shell - echo "==============================================" - echo "Starting up middleman at http://localhost:4567" - echo "If it does not come up, check the ~/middleman.log file for any error messages" - cd /vagrant - bundle exec middleman server --watcher-force-polling --watcher-latency=1 &> ~/middleman.log & - SHELL -end diff --git a/config.rb b/config.rb deleted file mode 100644 index 6f8b677..0000000 --- a/config.rb +++ /dev/null @@ -1,63 +0,0 @@ -# Unique header generation -require './lib/unique_head.rb' - -# Markdown -set :markdown_engine, :redcarpet -set :markdown, - fenced_code_blocks: true, - smartypants: true, - disable_indented_code_blocks: true, - prettify: true, - strikethrough: true, - tables: true, - with_toc_data: true, - no_intra_emphasis: true, - renderer: UniqueHeadCounter - -# Assets -set :css_dir, 'stylesheets' -set :js_dir, 'javascripts' -set :images_dir, 'images' -set :fonts_dir, 'fonts' - -# Activate the syntax highlighter -activate :syntax -ready do - require './lib/monokai_sublime_slate.rb' - require './lib/multilang.rb' -end - -activate :sprockets - -activate :autoprefixer do |config| - config.browsers = ['last 2 version', 'Firefox ESR'] - config.cascade = false - config.inline = true -end - -# Github pages require relative links -activate :relative_assets -set :relative_links, true - -# Build Configuration -configure :build do - # We do want to hash woff and woff2 as there's a bug where woff2 will use - # woff asset hash which breaks things. Trying to use a combination of ignore and - # rewrite_ignore does not work as it conflicts weirdly with relative_assets. Disabling - # the .woff2 extension only does not work as .woff will still activate it so have to - # have both. See https://github.com/slatedocs/slate/issues/1171 for more details. - activate :asset_hash, :exts => app.config[:asset_extensions] - %w[.woff .woff2] - # If you're having trouble with Middleman hanging, commenting - # out the following two lines has been known to help - activate :minify_css - activate :minify_javascript - # activate :gzip -end - -# Deploy Configuration -# If you want Middleman to listen on a different port, you can set that below -set :port, 4567 - -helpers do - require './lib/toc_data.rb' -end diff --git a/deploy.sh b/deploy.sh deleted file mode 100755 index 9dbd7db..0000000 --- a/deploy.sh +++ /dev/null @@ -1,226 +0,0 @@ -#!/usr/bin/env bash -set -o errexit #abort if any command fails -me=$(basename "0ドル") - -help_message="\ -Usage: $me [-c FILE] [++BASE URL
+
https://api.recursion.space
+The Recursion.Space API is built on REST principles. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
+ +API authentication is handled by a unique key generated for your account.
+ +If you need API support or would like to see how others are implementing the platform you will find our staff and community through our Discord server.
+ + + + +++AUTHENTICATED REQUEST
+
# With shell, you can just pass the correct header with each request
+curl "https://api.recursion.space/v1/" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++ +A sample placeholder API key is included in all the examples here, replace with your key prior to making API requests.
+
Recursion.Space uses API keys to allow access to the API. You can obtain an API key under the developer tab on your dashboard.
+ +Your API key grants privlaged access to your account and by extention spaces, so be sure to keep it secure! Do not share your API keys in publicly accessible areas such as GitHUB, client-side code, and so forth.
+ + +Client, or language, libraries provide a streamlined method for you to consume the API in the native language of your application. Libraries will be added as they become available, to find community libraries vist the Recursion.Space Discord.
+These are the current libraries officially maintained by Recursion.Space on GitHub.
+ + +++Handling Errors
+
# Select a client library to see examples of handling different kinds of errors.
+Recursion.Space API uses conventional HTTP response codes to indicate the success or failure of an API call. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Recursion.Space servers (these are rare).
| Error Code | +Meaning | +
|---|---|
| 400 | +Bad Request -- Your request is invalid. | +
| 403 | +Authentication -- You do not have permission to view resource. | +
| 405 | +Bad Method -- Method used (GET, POST, DELETE, PUT) not allowed. | +
| 418 | +I'm a teapot. | +
+++
GET/v1/spaces
GET/v1/spaces/{space_id}
curl "https://api.recursion.space/v1/spaces/{xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx}" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++RESPONSE
+
[
+ {
+ "id":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
+ "name":"The Void",
+ "address":"1331 12th Ave",
+ "address2":"STE 205",
+ "city":"Altoona",
+ "state":"PA",
+ "zipcode":"16601",
+ "country":"United States",
+ "email":"demo@recursion.space",
+ "timezone":"UTC"
+ }
+]
+Return a list of spaces owned by the API Token holder, or return information on a specific space by filtering with the space id.
+| Parameter | +Type | +Description | +
|---|---|---|
| id | +string | +The unique space identifier. | +
| name | +string | +Your name for the space. | +
| address | +string | +The physical address of the space. | +
| address2 | +string | +Address line for STE, UNIT, BLD, ect. | +
| city | +string | +City component of the spaces address. | +
| state | +string | +State component of the spaces address. | +
| zipcode | +string | +Zipcode component of the spaces address. | +
| country | +string | +Country where the space is located. | +
| string | +Primary/General email for the space. | +|
| timezone | +string | +Selected timezone for the space. | +
+++
GET/v1/operators/{space_id}
curl "https://api.recursion.space/v1/operators/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++RESPONSE
+
[
+ {
+ "facility":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
+ "cardNumber":"0123456789",
+ "phone_number":,
+ "address":"1331 12th Ave",
+ "city":"Altoona",
+ "state":"PA",
+ "zip_code":"16601",
+ "username":"DemoUser",
+ "first_name":"Lorem",
+ "last_name":"Ipsum",
+ "email":"demo@recursion.space",
+ },
+]
+Retrieve information for all operators ("admins") for the selected space.
+| Parameter | +Type | +Description | +
|---|---|---|
| facility | +string | +The facility id for which the operator belongs to. | +
| cardNumber | +string | +The RFID number assigned to the operator. | +
| phone_number | +string | +Operator provided phone number. | +
| address | +string | +Operator provided address. | +
| city | +string | +City component of address provided by operator. | +
| state | +string | +State component of address provided by operator. | +
| zip_code | +string | +Zip Code component of address provided by operator. | +
| username | +string | +Username associated with the operators account. | +
| first_name | +string | +Operators first name. | +
| last_name | +string | +Operators last name. | +
| string | +Operator provided email. | +
+++
GET/v1/members/{space_id}
curl "https://api.recursion.space/v1/members/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+ -H "Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++RESPONSE
+
[
+ {
+ "cardNumber":"0123456789",
+ "access_group":123,
+ "phone_number":"calico",
+ "address":6,
+ "city":7,
+ "state":,
+ "zip_code":,
+ "username":,
+ "first_name":,
+ "last_name":,
+ "email":,
+ "restricted_nodes":[]
+ },
+]
+Retrieve information for all members associated with a space.
+| Parameter | +Type | +Description | +
|---|---|---|
| cardNumber | +string | +The RFID number assigned to your member. | +
| access_group | +integer | +The ID for the access group that the member belongs to. | +
| phone_number | +string | +Member provided phone number. | +
| address | +string | +Member provided address. | +
| city | +string | +City component of address provided by member. | +
| state | +string | +State component of address provided by member. | +
| zip_code | +string | +Zip Code component of address provided by member. | +
| username | +string | +Username associated with the members account. | +
| first_name | +string | +Members first name. | +
| last_name | +string | +Members last name. | +
| string | +Member provided email. | +|
| restricted_nodes | +array | +List of IDs the member does not have access to within their access group. | +
++GET /v1/permissions/{space_id}
+
curl "https://api.recursion.space/v1/permissions/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++RESPONSE
+
[
+ {
+ "id":2,
+ "name":"Max",
+ "startTime":"unknown",
+ "endTime":5,
+ "monday":10,
+ "tuesday":false,
+ "wednesday":false,
+ "thursday":false,
+ "friday":false,
+ "saturday":false,
+ "sunday":false,
+ "twenty_four_seven":true,
+ "default_fallback":false,
+ "facility":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
+ "allowedNodes":[19]
+ }
+]
+Returns the available permissions, or access groups, for the space.
+| Parameter | +Type | +Description | +
|---|---|---|
| id | +integer | +The ID of the access group. | +
| name | +string | +Name descriptor for the access group. | +
| startTime | +integer | +The daily start time when access is permitted for this group. | +
| endTime | +integer | +The daily end time when access is no longer permitted for this group. | +
| monday | +boolean | +True if access is is allowed for a Monday, otherwise false. | +
| tuesday | +boolean | +True if access is is allowed for a Tuesday, otherwise false. | +
| wednesday | +boolean | +True if access is is allowed for a Wednesday, otherwise false. | +
| thursday | +boolean | +True if access is is allowed for a Thursday, otherwise false. | +
| friday | +boolean | +True if access is is allowed for a Friday, otherwise false. | +
| saturday | +boolean | +True if access is is allowed for a Saturday, otherwise false. | +
| sunday | +boolean | +True if access is is allowed for a Sunday, otherwise false. | +
| twenty_four_seven | +boolean | +Set true if group is allowed access 24 hours a day, 7 days a week. | +
| facility | +string | +The ID for which the access group belongs to. | +
| allowedNodes | +integer array | +List of nodes permitted to be used within this group. | +
Modules refer to the safety and training "courses" that can be created within the system.
++++
GET/v1/modules/{space_id}
curl "https://api.recursion.space/v1/modules/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+++RESPONSE
+
[
+ {
+ "id":#,
+ "name":"Proper Tool Lesson",
+ "brand":"DeWaukee",
+ "model":"TorqueHammer 3000",
+ "general_reading":"<p>Lorem ipsum dolor sit amet....</p>",
+ "video":"https://youtube.com",
+ "classmaker":"https://classmaker.com",
+ "required_training":true,
+ "classlink":"https://calendar.com",
+ "archive":false
+
+ },
+]
+Returns the details for all modules created at the selected space.
+| Parameter | +Type | +Description | +
|---|---|---|
| id | +integer | +Identification number of the module. | +
| name | +string | +The user defined name for the module. | +
| brand | +string | +Brand name of tool the module is associated with. | +
| model | +string | +Model name of the tool the module is associated with. | +
| general_reading | +string | +HTML formatted reading material. | +
| video | +string | +URL for an instructional video for the module. | +
| classmaker | +string | +URL for the test/quiz of the module. | +
| required_training | +boolean | +Indicates if in-person training is a requirement. | +
| classlink | +string | +URL to the registration location for the in-person training. | +
| archive | +boolean | +Indicator if the module is active or not. | +
+++
GET/v1/moduleprogress/{username}
POST/v1/moduleprogress/{username}
curl "https://api.recursion.space/v1/moduleprogress/username" \
+ -H "Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
+
+curl -X POST "https://api.recursion.space/v1/moduleprogress/username" \
+ -H "Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
+ -d "module=##"
+ -d "param=value"
+++GET RESPONSE
+
[
+ {
+ "module":#,
+ "general_reading_completed":true,
+ "video_completed":false,
+ "classmaker_initiated":true,
+ "classmaker_completed":false,
+ "required_training_initiated":false,
+ "required_training_completed":false,
+ "username":"AwesomeMember"
+ },
+]
+GET: Returns the progress for all modules associated with a selected user.
+POST: Update one or more progress parameters for a selected module.
| Parameter | +Type | +Description | +
|---|---|---|
| module | +integer | +The ID of the modules. | +
| general_reading_completed | +boolean | +An indication of the user has clicked open the reading material. | +
| video_completed | +boolean | +And indication if the user has viewed the video of the module. | +
| classmaker_initiated | +boolean | +An indicator that the user has clicked the associated exam link. | +
| classmaker_completed | +boolean | +Set by the admin once the user has module exam has been passed sucessfully. | +
| required_training_initiated | +boolean | +An indicator that he user has clicked to schedule a training time. | +
| required_training_completed | +boolean | +Set by the admin once the required training has been complete. | +
| username | +string | +Username associated with the operators account. | +
Registers a UUID with Recursion.Space as a valid Pod identifier. +This step authorizes a Pod UUID under the user's account/API token, so that the device can register itself in the next step.
+ ++++
POST/v1/pods
curl -X POST "https://api.recursion.space/v1/pods" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
+ -d '{"uuid": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
+| Field | +Type | +Required | +Description | +
|---|---|---|---|
uuid |
+string (UUID) | +true | +The unique identifier for the Pod. Must be a valid UUID format. | +
++Example Successful Response (HTTP 201 Created)
+
{
+ "uuid":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx"
+}
+| Field | +Type | +Description | +
|---|---|---|
uuid |
+string | +The unique identifier for the Pod. | +
Provision a Pod with Recursion.Space, this will provide the Pod with a token to use for future requests.
+ ++++
POST/v1/pods/{uuid}/provision
curl -X POST "https://api.recursion.space/v1/pods/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx/provision" \
+ -H "Content-Type: application/json" \
+ -d '{"serial": "xxxxxxxxxxxx"}'
+| Field | +Type | +Required | +Description | +
|---|---|---|---|
serial |
+string | +true | +The serial number of the Pod. | +
++Example Successful Response (HTTP 201 Created)
+
{
+ "uuid":"xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
+ "serial":"xxxxxxxx",
+ "token":"pod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}
+| Field | +Type | +Description | +
|---|---|---|
uuid |
+string | +The unique identifier for the Pod. | +
serial |
+string | +The serial number of the Pod. | +
token |
+string | +The Pod's unique token for future requests. | +