This article contains all MUST HAVE items for a successful integration with our farmerswife (fw) REST API.
See the latest fw REST API changes on these Release Notes:
NEW => 6.6 SP2 RC2 rev. 19671
=> 6.5 SP1 RC1
=> 6.5 Beta 7
=> 6.5 Beta 6
To get the latest documentation see below this section: "1.5 Supported resources and actions documentation"
REST API Version 1
- 1. Getting Started
- 1.3 Enabling GZip to compress HTTP responses
- 1.4 How to import the Postman Collection to Postman for a quick start
- 1.5 Supported resources and actions documentation
Can I use the REST API?
Yes, if your farmerswife system is at least on version 6.4; recommended to be on the latest available version!
The fw REST API is a licensed feature, but free of charge.
Please request your license from email@example.com.
Does the farmerswife support agreement also include API support?
It is not part of your normal farmerswife support agreement. You can order "API 3rd party development consultancy" for us to assist you and for requests to enhance the fw REST API functionality.
1. Getting Started
The farmerswife (fw) REST API allows you to connect your own "application" to your fw Server to "get", "update" and "add" certain data without having to use these fw end-user Client interfaces fw Client Desktop app, iOS fw app or Web/Mobile Client to access the system.
This page documents the currently available resources in our fw REST Api, along with "json" schemas, expected HTTP response codes and sample requests and responses. These are all contained within the below mentioned "swagger.json" file.
The REST API is a licensed feature. And getting it licensed is free of charge.
Your farmerswife system needs to at least run on v6.4 and for latest changes on v6.6 SP2 RC2 rev. 19667 or later.
The license will include a specific Application ID that will allow you to authenticate and interact with your fw Server via the REST API.
IMPORTANT: Using the farmerswife REST API IS A "3rd party integration"!
Support in any form is not covered by active "Gold", "Silver" or "cloud hosted" support agreements.
Each 3rd party integration is different.
This typically requires in-dept end-user knowledge of both systems: farmerswife and the 3rd party system(s) to be integrated with.
Day-based "3rd Party Integration Consultancy" can be purchased to facilitate limited 3rd level technical support if needed.
Potentially missing functionality is subject to purchased prioritized development.
To accomplish a smooth as possibly integration experience, your integration goal within farmerswife must be clearly defined.
This means, the "head" farmerswife user builds a screen-shot story-board together with your own developer or programmer. This solves multiples purposes. It's not only the step-by-step instruction set for the developer. This is also the source for troubleshooting
Our technical support and development resources are limited.
Please contact firstname.lastname@example.org to get a valid license before starting any kind of development.
The REST API uses a stateless authentication system based on "Json Web Tokens" (JWT) according to the industry standard: RFC 7519.
Once you have the token you need to add the Authorization header in every request to access protected resources. The security schema must to be "Bearer" and the header should look like this:
Authorization: Bearer ACCESS_TOKEN_HERE
Every token is linked to an existing fw user!
We more than strongly recommend that you create and use a dedicated farmerswife Web User account in your system to facilitate the access via the REST API!
This also means to create a dedicated "Web Permission Profile" only for this user! And ONLY enable the Settings which are needed for the intended integration to work!
You must ensure that the "fw REST API" user account you are using has the permissions needed on their Web Permission Profile for the actions you want to perform.
For instance, when editing the Web Permission Profile Settings (fw desktop Client ▶ Object Manager ▶ Modify User ▶ Web Permission Profile):
- Limit users to only be able to create time-reports for themselves and not for other users:
- Timereports ▶ Not Other Users Time = Unchecked
- Give permissions to a user so they can create Projects via the API (both settings are necessary):
- Projects ▶ Show ▶ All Projects = Checked
- Projects ▶ Allow Editing Project ▶ Always = Checked
- Projects ▶ Show ▶ All Projects = Checked
1.2.1 Token Expiration
The JWT Token expires when:
- The user you authenticated with is modified in farmerswife by an Advanced User with according Permissions.
- The fw Server is restarted.
- The Token you are using, was explicitly expired by using the method DELETE on /auth/token.
If a protected resource is requested by using an expired or invalid token, the fw Server will respond:
HTTP Status Code: 401 (Unauthorized)
HTTP Response Body
"description": "Expired or Illegal token.",
In this case you must handle the 401 Unauthorized exception and request a new access token.
1.3 Enabling GZip to compress HTTP responses
Optionally fw REST API allows you to enable GZip compression on HTTP Responses. A custom HTTP Header has to be added to the request in order to enable GZip compression:
1.4 How to import the "swagger.json" file to Postman to use all End Points
- Download & Install Postman from https://www.getpostman.com
- Open Postman > Go to settings > SSL certificate verification should be OFF
- fw Server running with a valid fw REST API appID within it's license.
Steps to Import into Postman:
- Attached to this page is the latest "swagger.json" file, that you can import into Postman.
- Open Postman > Import > Import File and select the latest swagger.json" file download from this page.
1.5 Supported resources and actions documentation
The fw REST API only supports purchased and most requested resources and actions.
All available resources and actions are the ones described in this "Swagger Json" file v0.7, last updated 02-November 2020, which is in sync with changes up to v6.6 SP2 RC2 rev. 19671 and later:
fw REST API supported resources and actions download the latest v0.7 here => Swagger.json
For viewing this "Swagger.json" file, we recommend to just copy and paste its contents into the online Swagger Editor: https://editor.swagger.io/
See this screenshot from the "Swagger.json" Api Reference v0.7, to quickly see the available resources that are currently supported by the fw v6.6 REST API (last updated 02-November-2020):