OADA/oada-docs

Welcome to the Open Ag Data Alliance (OADA).

The important stuff: API Docs

Getting Started	Specs
Intro to the OADA API: Irrigation	Rest API Spec
Intro to the OADA API: Trellis
Intro to OADA Authentication and Authorization	Authorization and Authentication
Deploy+Ops

Overview

The purpose of the Open Ag Data Alliance is to develop a standard API framework for automated data exchange. If a person has data stored in one place, and would like an app or service to be able to access it, they need only know the top-level domain where their data sits in order for the app or service to use it.

Getting Started

The best way to get familiar with the OADA API is to use it. Do that:

Install the OADA demo server: git clone git@github.com:OADA/oada-srvc-docker.git
Start up the server (it runs on localhost at port 80). NOTE: if you are developing, you might want to turn off TLS errors for the node services for your self-signed certificates by adding the NODE_TLS_REJECT_UNAUTHORIZED=0 environment variable.
```
cd oada-srvc-docker
docker-compose up -d
```
Learn about your server and make sure it's up. Open a browser and go to (https://localhost/.well-known/oada-configuration). Look for oada_base_uri (where the data is), and authorization_endpoint (where to ask for a token). NOTE: the local SSL certificate is self-signed. You have to approve it in your browser.
Get an authorization token to your server: Go to http://client.oada-dev.com, enter localhost in the box beside "Get Access Token" and enter trellis:all in the box beside it labeled "Scope". Click "Get Access Token". Submit the default username/password on the next screen, then click "Allow".
Copy the access_token. Looks something like its8IrYYjlZba_uhdnVMjRNv6FWnZYA3SkCWdEdFa
Get an API tool like Insomnia. NOTE: Postman currently has an issue with Express that leads to PUT requests taking up to 65 seconds. Insomnia has no such issue, hence why we recommend using it. Postman works fine with GET's.
Discover what data is on your server for your token. In Insomnia, do a GET to https://localhost/bookmarks. Without an Authorization: header it will fail. Add it with the token you copied:
```
Authorization: Bearer its8IrYYjlZbuhdnVMjRNv6FWnZYA3SkCWdEdFa
```
Now you should get back some JSON listing the data that's available.
Add some data to your server. In Insomnia (Postman has issues with Express, so use Insomnia) with the same Authorization: header, do a PUT to https://localhost/bookmarks/theknights with the body:
```
{
  "whosay": "Ni!"
}
```
Add the Content-Type: application/vnd.oada.bookmarks.1+json header to the request, too.
And get it back: do a GET to https://localhost/bookmarks again and you should see your new data data: now the resource has a key named theknights.

Read up on the Rest API Spec with examples to learn how to create resources, link them between documents, track changes, and more.

Examples: Demonstration specs

Demonstrations

Contributing

Developer Guidelines

Questions

For contributors to the OADA project, the best method for contact is the oada-dev mailing list on Google Groups. For those just getting started, the oada-users mailing list on Google Groups is a good place to ask questions.

We also now have a Gitter channel to chat (see the badge at the top of this readme).