From 1535214781c0ef0fedaadd67a1171ef9092dfc1d Mon Sep 17 00:00:00 2001 From: Albert Liu Date: Thu, 18 Oct 2018 16:41:08 -0400 Subject: [PATCH 1/2] added content to adapters.md --- architecture/adapters.md | 85 ++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 12 deletions(-) diff --git a/architecture/adapters.md b/architecture/adapters.md index 1c7cf98..b93a12c 100644 --- a/architecture/adapters.md +++ b/architecture/adapters.md @@ -1,5 +1,5 @@ # Service Map ## Welcome! @@ -12,16 +12,38 @@ They can be written in any language, and must simply respond to a set of HTTP en ## Basic Concept Here's a diagram illustrating the basic concept of Yacs and adapters: - + - + +This isn't technically correct. Every adapter is polled on a fixed interval, and Yacs saves the combined result + +When Yacs needs information that isn't stored in its database, it sends an HTTP request to the adapter that is responsible for that information. Then that adapter works its magic, and sends the information back in JSON format. This document is going to focus on the [`yaml-rpi`][yaml-rpi-adapter] adapter and use its code in examples. The document `app.rb` will also be edited for clarity to this: + +``` ruby +require 'sinatra' +require 'sinatra/json' +require 'oj' +require 'yaml' + +set :bind, '0.0.0.0' +set :port, 4600 + +ENV['YAML_SOURCE'] ||= 'schools-and-subjects.yml' + +get "/:term_shortname" do + file = open(ENV['YAML_SOURCE']) + yaml_content = YAML.load(file) + json yaml_content +end +``` ## Data Source -The first thing your adapter needs is a place to get data from. In the `yaml-rpi` adapter, that place is a file called `schools-and-subjects.yml`. +The first thing your adapter needs is a place to get data from. In the `yaml-rpi` adapter, that place is a file called `schools-and-subjects.yml`: ```yml @@ -41,15 +63,22 @@ schools: ``` -Now that we have a place to get information from, we need to load it into the adapter. We do so with this line: +Now that we have a place to get information from, we need to load it into the adapter. We do so with this line in `app.rb`: -```ruby +``` ruby + +# ... +require 'yaml' ENV['YAML_SOURCE'] ||= 'schools-and-subjects.yml' +# ... + file = open(ENV['YAML_SOURCE']) + yaml_content = YAML.load(file) + # ... ``` -Here, `ENV` is just a container for the environment variables in Ruby, and `'YAML_SOURCE'` is the name of the environment variable. We're setting its value to the name of the file, `'schools-and-subjects.yml'`, and essentially that 'loads' it into the adapter. +Here, `ENV` is just a container for the environment variables in Ruby, and `'YAML_SOURCE'` is the name of the environment variable. We're setting its value to the name of the file, `'schools-and-subjects.yml'`. Then, when the adapter is asked for information, it first opens a file at the location, then uses a function from the `'yaml'` package to convert the file's contents to a ruby object. ## JSON API and REST Your adapter then needs to convert the data that it loaded into a format that Yacs can read - that's what the JSON API is for. This document will give a brief explanation of the API - a more in-depth explanation can be found [here][json-api]. @@ -68,17 +97,49 @@ The JSON API is based off of JavaScript Object Notation: ``` -Notice that objects are surrounded by `{curly brackets}`, and both attributes and values are surrounded by `"double quotes"`. Each attribute-value pair is specified by a single line, with a colon separating attributes and values, and attribute-value pairs are separated by a comma. Note that spacing is irrelevant to the formatting of the document except in strings -- anything between double quotes must be on a single line. +Objects are surrounded by `{curly brackets}`, and both attributes and values are surrounded by `"double quotes"`. Each attribute-value pair is specified by a single line, with a colon separating attributes and values, and attribute-value pairs are separated by a comma. Spacing is irrelevant to the formatting of the document except in strings -- anything between double quotes must be on a single line. Finally, there is no syntax for making comments. + +In the `yaml-rpi` adapter, this is done through these lines in `app.rb`: -In the `yaml-rpi` adapter, this is done through +```ruby + +require 'sinatra/json' +require 'oj' + +# ... + json yaml_content + +``` + +`require 'sinatra/json'` and `require 'oj'` tell ruby to load the Sinatra package's JSON helper function and the Optimized JSON package respectively. Then when the adapter needs to convert the data in `yaml_content` to JSON, the `json` function from `'sinatra/json'` is called. ## HTTP Protocol + + +```ruby + +# ... +require 'sinatra' + +set :bind, '0.0.0.0' +set :port, 4600 + +# ... + +get "/:term_shortname" do + # ... +end + +``` ## Implementation Agnostic +Notice that the only parts of the adapter that actually interact with YACS itself are format of the data (JSON) and the data transfer protocol (HTTP). Since both of these systems are implementation agnostic, you can write your adapter in whatever language you want! As long as it responds to HTTP requests with a JSON object, it's good to go! [yacs-adapters]: https://github.com/YACS-RCOS/yacs/tree/master/adapters [yaml-rpi-adapter]: https://github.com/YACS-RCOS/yacs/tree/master/adapters/yaml-rpi [json-api]: http://jsonapi.org/format/ ---> \ No newline at end of file + From c73c9a9ea0dc5c858c44a1a17bd53cb5a11b4c61 Mon Sep 17 00:00:00 2001 From: Albert Liu Date: Thu, 18 Oct 2018 21:21:47 -0400 Subject: [PATCH 2/2] commiting changes, stopping work for a while --- architecture/adapters.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/architecture/adapters.md b/architecture/adapters.md index 647cd02..5bf595b 100644 --- a/architecture/adapters.md +++ b/architecture/adapters.md @@ -21,8 +21,7 @@ DIAGRAM GOES HERE --> This isn't technically correct. Every adapter is polled on a fixed interval, and Yacs saves the combined result - -When Yacs needs information that isn't stored in its database, it sends an HTTP request to the adapter that is responsible for that information. Then that adapter works its magic, and sends the information back in JSON format. This document is going to focus on the [`yaml-rpi`][yaml-rpi-adapter] adapter and use its code in examples. The document `app.rb` will also be edited for clarity to this: +Yacs polls each adapter at a fixed interval by sending an HTTP request. Then that adapter works its magic, and sends the information back in JSON format. This document is going to focus on the [`yaml-rpi`][yaml-rpi-adapter] adapter and use its code in examples. The document `app.rb` will also be edited for clarity to this: ``` ruby require 'sinatra'