Getting Started | Specs |
---|---|
Intro to the OADA API: Trellis | |
Deploy+Ops | |
Intro to OADA Authentication and Authorization | Authorization and Authentication |
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, providing permission when setting up the connection.
From a developer's perspective, OADA is an API specification and an open source implementation of that API spec. That installable implementation can be found under this Github organization at oada-srvc-docker. This is sort of like learning SQL as a query language, and then installing MySQL to use it. Learning the OADA API is the language, and running the open source implementation lets you use it.
A microservice architecture is such a core part of the OADA model that the service itself is a suite of docker containers. Before diving in, you may find it helpful to familiarize yourself with docker and docker-compose.
The best way to get familiar with the OADA API is to use it. Latest instructions for installing and running the reference OADA implementation can be found at https://github.com/oada/server. This will get you setup with a locally running instance of OADA and a token you can use to make API requests.
-
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), andauthorization_endpoint
(where to ask for a token). IMPORTANT NOTE: if you did not usemkcert
to setup your SSL certificate, then your browser will not trust it. You will have to manually approve it in your browser to see the configuration page. -
Discover what data is on your server for your token. In Insomnia, do a
GET
tohttps://localhost/bookmarks
. Without anAuthorization:
header it will fail. Add it the token you created when you setup your instance:Authorization: Bearer the_token
Now you should get back some JSON listing the data that's available, which in this case is likely just an empty JSON object if you just setup your server.
-
Add some data to your server. In Insomnia, with the same
Authorization:
header, do aPUT
tohttps://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
tohttps://localhost/bookmarks
again and you should see your new data data: now the resource has a key namedtheknights
. -
Explore: Create a resource. You can assign your own resource ID with a PUT, or you can ask the server to create an ID for you and execute the PUT for you with that random id.
PUT /resources/123 { "hello": "world" }
That will create resource
resources/123
if it doesn't exist, and put that body as the initial contents for_rev
1.POST /resources { }
That will create a random ID and create it with an empty body. The ID that it created will be returned in the
Content-Location
header on the response. -
Link: Link your new resource. In order to find your resource again, you need to link it into your user's
/bookmarks
tree. A link is just an object containing an_id
. To link your newresources/123
resource under the path/bookmarks/the_most_important_resource
:PUT /bookmarks/the_most_important_resource { "_id": "resources/123" }
or, you can merge it into bookmarks rather than PUT-ing to the key directly:
PUT /bookmarks { "the_most_important_resource": { "_id": "resources/123" } }
Now, whenever you get the
the_most_important_resource
key from/bookmarks
, OADA will recognize it as a link toresources/123
and return that resource to you directlyGET /bookmarks/the_most_important_resource
returns the contents of
resources/123
.
Read up on the Rest API Spec with examples to learn how to create resources, link them between documents, track changes, add services or custom modules, and more.
To see an example of how to solve a particular problem using the OADA API, please refer to the documentation from the Pork Hackathon: PorkHack21.
-
oada/oada-docs The core API spec and associated documentation.
-
oada/server The Docker-based reference implementation of the OADA API.
-
oada/formats Sets of schemas and examples for various OADA content types.
-
oada/oada-certs A command line tool and javascript library for signing things and validating those signatures. It contains most of the core signature logic used by trellisfw-signatures. You can use it in the
admin
container to setup a new domain on youroada
installation (to sign the developer certificate), or you can use it to generate signing key pairs and convert them to JWK's. -
oada/oada-id-client-js A javascript library that simplifies performing authorization with an OADA server. It handles initiating OAuth2 requests and returning the resulting authorization tokens.
-
oada/client A Typescript/JS library for Node and the Browser that handles much of the interaction with an OADA cloud: connecting, keeping an open websocket for changes, setting watches, and concurrency-protected "tree"-based PUTs that ensure a given path exists properly when executing a PUT.
-
oada/jobs A Typescript/javascript library that simplifies creating a microservice which listens to a job queue for things that it should do.
-
oada/types A wrapper for oada/formats that creates and publishes typescript types from
formats
json schemas.
1: How is OADA related to Trellis?
Trellis is simply a different "brand" name for OADA, targeted toward the food supply chain industry.
Trellis uses OADA as its API, and adds some formats
For contributors to the OADA project, the best method for contact is the oada-dev public Slack team.