This article contains all MUST-HAVE items for successful integration with our farmerswife (fw) REST API.
See the latest fw REST API changes as per these Release Notes (click here) :
NEW => Multiple changes are work-in-progress on v6.8 Beta (rev. 20223 swagger v0.8.6; contact supportATfarmerswife.com for more info)
=> 6.7 Beta 2 rev. 19746 ... swagger v0.8.1 more info below
=> 6.6 SP2 RC2 rev. 19671 ... swagger v0.7 more info below
=> 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 firstname.lastname@example.org.
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 the 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-depth end-user knowledge of both systems: farmerswife and the 3rd party system(s) to be integrated.
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 possible integration experience, your integration goal within farmerswife must be clearly defined.
This means the "Lead" farmerswife user builds a screen-shot storyboard together with your own developer or programmer. This solves multiple 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 email@example.com 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 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 access via the REST API!
This also means creating 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 = Checked
- 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 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 exceptions 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 its license.
Steps to Import the "swagger.json" file into Postman:
- Attached at the bottom of this page is the latest publicly available "swagger.json" file, that you can import into Postman (or other programming tools), which will then add all available end points into a new "Collection" in Postman.
- Open Postman > use "Import" button > "Upload Files" button and select the latest swagger.json" file downloaded from this page or the latest one you might have received from farmerswife Support.
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.8.1 - For customers on v6.7 Beta:
Last updated 22. January 2021
This is in sync with changes up to v6.7 Beta 2 rev. 19746 and later.
fw REST API supported resources and actions download the latest v0.8.1 here => Swagger.json
v0.7 - For customers on v6.6 Service Pack 2, please continue using this info:
Last updated 2nd November 2020
This is in sync with changes up to v6.6 SP2 RC2 rev. 19671 and later.
fw REST API supported resources and actions download the v0.7 here => Swagger.json
For viewing this "Swagger.json" file, we recommend just copying and pasting its contents into the online Swagger Editor: https://editor.swagger.io/
See the following screenshot from the "Swagger.json" API Reference v0.8.1, to quickly see the available resources that are currently supported by the fw v6.6 REST API (last updated 02-March-2021):