## Farmmaps Documentation Overview
### 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.  

## Getting started
The main starting point for Farmmaps API access is the REST API.
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.

### Environments

At the moment, FarmMaps provides two environments for development.

* https://test.farmmaps.eu (testing environment, data is not persistent)
* https://acc.farmmaps.eu (acceptation environment, data IS persistent)

When developing your application, using the **acceptation environment is highly recommended**.

### Obtaining 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:

* https://test.farmmaps.eu (for the acceptation environment)
* https://test.farmmaps.eu(for the testing environment)

It is also possible to get credentials to use the cleint credential flow, please contact FarmMaps for further information.

Once you have an account, you can create a JSON Web Token to authenticate at the API endpoint.

### Authentication & Authorization flow
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.

So, in the authentication flow there are two parties:
* 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 general flow (for FarmMaps) is as follows:

* 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 creates an authentication request for the Open ID Provider.
* The user is redirected to the "Log in page" of the OpenID Provider.
* 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.

Now that the user is back at your application 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.

To continue please see one of the articles below:

- [Integrating FarmMaps Open ID Connect into your application](Integrating-FarmMaps-OIDC.md)
- [Creating an access token for testing.](Create-access-token.md)

## Using the FarmMaps 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://acc.farmmaps.eu/swagger/)
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.

We provide the following guides:
* [Uploading a file](Upload-a-file.md)
* [Creating a cropfield](Create-a-cropfield.md)
* [Running a task](Running-tasks.md)

Generally, tasks can be run in the same way.
However, each specific task has it's own inputs and properties. 
How these work can be found in the use task examples below.
 
### <a name="task-examples"></a>Task examples
* [VRAPoten-API](VRAPoten-API.md)
* [VRANbs-API](VRANbs-API.md)
* [VRAHerbicide-API](VRAHerbicide-API.md)
* [VRAHaulmkilling-API](VRAHaulmkilling-API.md)
* [Blight-API](Blight-API.md)