README.md

Hack for the Sea Data Lake

Repository for Hack for the Sea data. Sponsored by Microshare.

Table of Contents

• Installation / Getting Started
  • I. Register a new Hack for the Sea Application
  • II. Construct an Authorization URL and Obtain an Authorization Code
  • III. Authenticate Your Application
• Usage
  • Listing and Retrieving Data
  • Posting Data
  • Deleting Data
• Data Lake Schema
• Maintainers
• Contribute
• License

Installation / Getting Started

This document assumes you are working with a web application or a medium that supports HTTP.

Instructions for embedded hardware code and CLI tools coming soon.

I. Register a new Hack for the Sea Application

The Data Lake requires oAuth to use. Here's how to get credentials

1. Register a new Hack for the Sea account at http://hackforthesea.tech/accounts/register
2. For now, please email [email protected] to activate your account.
3. Once your account is activated, log in and you will be redirected to https://hackforthesea.tech/oauth/applications/
4. Create a new application with the following values.
   • Name: Choose your own name of your application i.e. Bathymetry Explorer
   • Client id: Leave as is
   • Client secret: Leave as is
   • Client type Select Confidential for now.
   • Authorization grant type: Select Authorization Code for now.
   • Redirect uris The URL that you wish to be redirected back to after authentication is complete. Typically the URL of your application itself.

II. Construct an Authorization URL and Obtain an Authorization Code

1. Visit this URL: https://hackforthesea.tech/oauth/authorize/?response_type=code&state=random_state_string&client_id=[YOUR_CLIENT_ID], substituting YOUR_CLIENT_ID with the client ID of the application you created.
2. Review the permissions requested by the application, and click "Approve"
3. You will then be redirected to your applications Redirect URI, which will have a "code" parameter, like this: https://[REDIRECT_URI]/?state=random_state_string&code=j7SAsPilPPIWHmJ05tiEd02t4hWQAJ

III. Authenticate Your Application

jQuery Example:

$.ajax({
  url: "https://hackforthesea.tech/oauth/token/",
  method: "POST",
  data: {
    csrfmiddlewaretoken: getCookie('csrftoken'),
    grant_type: "authorization_code",
    code: "AUTH_CODE_FROM_PREVIOUS_STEP",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    redirect_uri: "REDIRECT_URI_MUST_MATCH_YOUR_APP"
  },
  success: function(res) {
    setCookie('h4ts_access_token', res.access_token);
    setCookie('h4ts_token_type', res.token_type);
    setCookie('h4ts_expires_in', res.expires_in);
    setCookie('h4ts_refresh_token', res.refresh_token);
    setCookie('h4ts_scope', res.scope);
    window.location = "/app";
  }
})

Usage

Here are some jQuery AJAX requests that work.

Listing and Retrieving Data

// List
$.ajax({
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals?access_token=[ACCESS_TOKEN]",
  success: function(response) {
    console.log(response);
  }
});

// List with tags - as many as you want
$.ajax({
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals/tags/tag1/tag2/etc?access_token=[ACCESS_TOKEN]",
  success: function(response) {
    console.log(response);
  }
});

/******
Available query string params for list view
- details: boolean
  Will return matching objects with their details, false will only return main information

- page: int
  Specifies the requested page, defaults to 1

- perPage int
  Specifies the number of objects to be returned per page, defaults to 999

- sort: string
  Specifies if sorting needs to be applied and to which field in the data
********/

// Detail
$.ajax({
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals/5a0e304946e0fb0022f6f40d?access_token=[ACCESS_TOKEN]",
  success: function(response) {
    console.log(response);
  }
});

Posting Data

$.ajax({
  type: "POST",
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals?access_token=[ACCESS_TOKEN]",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify({ hello: "world" })
});

// With tags
$.ajax({
  type: "POST",
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals/tags/tag1/tag2/etc?access_token=[ACCESS_TOKEN]",
  contentType: "application/json",
  dataType: "json",
  data: JSON.stringify({ hello: "world" })
});

Deleting Data

$.ajax({
  url: "https://hackforthesea.tech/data/com.hackforthesea.globals/5a0e315b46e0fb002866b437?access_token=[ACCESS_TOKEN]",
  type: "DELETE"
});

Data Lake Schema

Objects in the data lake are stored in dot-notated keys, all beginning with com.hackforthesea. There are global objects, and project-spefific keys. The global objects are enumerated below, with links out to the individual projects as they are appropriate. Note that keys are singular - location, beach, animal, etc.

com.hackforthesea.global.location - Terrestrial locations with geodata included. Currently beaches in MA.

Maintainers

• Mark Henderson ([email protected])
• Sponsored by http://microshare.io

Contribute

The best thing you can do to contribute to the data lake is to put data into it! That means following the example set in the Usage section to create an app and send data to it.

License

Coming Soon