FarmMaps/Documentatie
8
0
Fork 0
Code Pull Requests Releases Activity

renamed Home to README

Browse Source
This commit is contained in:
Mark van der Wal 2020-05-07 18:46:02 +02:00
parent 1863ff393a
commit c46574580b
1 changed files with 73 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
Home.md → README.md
View File

@ -1,73 +1,73 @@
## Farmmaps Documentation Overview ## Farmmaps Documentation Overview
### The documentation is still work in progress and heavily subject to change! ### The documentation is still work in progress and heavily subject to change!
This page provides an index of the available documentation for the FarmMaps platform. This page provides an index of the available documentation for the FarmMaps platform.
## Getting started ## Getting started
The main starting point for Farmmaps API access is the REST API. The main starting point for Farmmaps API access is the REST API.
To get started, follow the steps below. To get started, follow the steps below.
The workflow and high-level architecture FarmMaps are documented on the [Farmmaps Workflow](Workflow.md) and [FarmMaps Main Components](Main-components.md) pages. The workflow and high-level architecture FarmMaps are documented on the [Farmmaps Workflow](Workflow.md) and [FarmMaps Main Components](Main-components.md) pages.
### Environments ### Environments
At the moment, FarmMaps provides two environments for development. At the moment, FarmMaps provides two environments for development.
* https://farmmaps.awtest.nl (testing environment, data is not persistent) * https://farmmaps.awtest.nl (testing environment, data is not persistent)
* https://farmmaps.awacc.nl (acceptation environment, data IS persistent) * https://farmmaps.awacc.nl (acceptation environment, data IS persistent)
When developing your application, using the **acceptation environment is highly recommended**. When developing your application, using the **acceptation environment is highly recommended**.
### Obtaining credentials ### Obtaining credentials
To get access to the API, you need an akkerweb development account (akkerweb development and farmmaps development use the same credentials). To get access to the API, you need an akkerweb development account (akkerweb development and farmmaps development use the same credentials).
These can be created at: These can be created at:
* https://awacc.nl (for the acceptation environment) * https://awacc.nl (for the acceptation environment)
* https://awtest.nl (for the testing environment) * https://awtest.nl (for the testing environment)
Once you have an account, you can create a JSON Web Token to authenticate at the API endpoint. Once you have an account, you can create a JSON Web Token to authenticate at the API endpoint.
### Authentication & Authorization flow ### Authentication & Authorization flow
FarmMaps uses Open ID Connect to provide user authentication and authorization services. FarmMaps uses Open ID Connect to provide user authentication and authorization services.
Open ID Connect (and OAuth beneath the surface) allows your application to access user information or data that is located at another service, without providing you the password to access the account. This is very useful if your application relies on data that needs to provided by this other service for your application to work. Open ID Connect (and OAuth beneath the surface) allows your application to access user information or data that is located at another service, without providing you the password to access the account. This is very useful if your application relies on data that needs to provided by this other service for your application to work.
So, in the authentication flow there are two parties: So, in the authentication flow there are two parties:
* The OpenID Provider (OP), holding the accounts database and providing the authentication services. * The OpenID Provider (OP), holding the accounts database and providing the authentication services.
* The Relying Party (RP), relying on authentication through the OP, to get access to the required data or endpoints. * The Relying Party (RP), relying on authentication through the OP, to get access to the required data or endpoints.
The general flow (for FarmMaps) is as follows: The general flow (for FarmMaps) is as follows:
* The user is at your application * The user is at your application
* Your application needs to access the farmmaps account of that user (i.e. to upload, modify or retrieve data) * Your application needs to access the farmmaps account of that user (i.e. to upload, modify or retrieve data)
* Your application creates an authentication request for the Open ID Provider. * Your application creates an authentication request for the Open ID Provider.
* The user is redirected to the "Log in page" of the OpenID Provider. * The user is redirected to the "Log in page" of the OpenID Provider.
* The user logs in at the login page. * The user logs in at the login page.
* On succesfull login, the user is redirected back to your application and the OpenID Provider returns an access token. * On succesfull login, the user is redirected back to your application and the OpenID Provider returns an access token.
Now that the user is back at your applicaiton and the application has an access token, it can then request resources from the OpenID provider. Now that the user is back at your applicaiton and the application has an access token, it can then request resources from the OpenID provider.
For each request, the access token needs to be sent along. This access token provides proof that the person sending the request is allowed to access the request and is who he/she claims to be. FarmMaps uses [JWT](https://jwt.io/introduction/) as the format for the access token. For each request, the access token needs to be sent along. This access token provides proof that the person sending the request is allowed to access the request and is who he/she claims to be. FarmMaps uses [JWT](https://jwt.io/introduction/) as the format for the access token.
To continue please see one of the articles below: To continue please see one of the articles below:
- [Integrating FarmMaps Open ID Connect into your application](Integrating-FarmMaps-OIDC.md) - [Integrating FarmMaps Open ID Connect into your application](Integrating-FarmMaps-OIDC.md)
- [Creating an access token for testing.](Create-access-token.md) - [Creating an access token for testing.](Create-access-token.md)
## Using the FarmMaps API ## Using the FarmMaps API
Once you have an access token, you can start querying the API. Once you have an access token, you can start querying the API.
A reference of the API can be found on [the swagger page](https://farmmaps.awacc.nl/swagger) A reference of the API can be found on [the swagger page](https://farmmaps.awacc.nl/swagger)
The API basics are uploading files, creating items and and running tasks to modify or convert data. The API basics are uploading files, creating items and and running tasks to modify or convert data.
For testing purposes, [Postman](https://www.postman.com) can be used to perform HTTP requests more easily. For testing purposes, [Postman](https://www.postman.com) can be used to perform HTTP requests more easily.
We provide the following guides: We provide the following guides:
* [Uploading a file](Upload-a-file.md) * [Uploading a file](Upload-a-file.md)
* [Creating a cropfield](Create-a-cropfield.md) * [Creating a cropfield](Create-a-cropfield.md)
* [Running a task](Running-tasks.md) * [Running a task](Running-tasks.md)
Generally, tasks can be run in the same way. Generally, tasks can be run in the same way.
However, each specific task has it's own inputs and properties. However, each specific task has it's own inputs and properties.
How these work can be found in the use task examples below. How these work can be found in the use task examples below.
### <a name="task-examples"></a>Task examples ### <a name="task-examples"></a>Task examples
* [VRAPoten-API](VRAPoten-API.md) * [VRAPoten-API](VRAPoten-API.md)
* [VRANbs-API](VRANbs-API.md) * [VRANbs-API](VRANbs-API.md)
* [VRAHerbicide-API](VRAHerbicide-API.md) * [VRAHerbicide-API](VRAHerbicide-API.md)