This article contains all MUST-HAVE items for a successful integration with the farmerswife (fw) REST API.
Can I use the REST API?
Your farmerswife system needs to at least run on the legacy v6.4.
We strongly recommend to be on the latest released farmerswife version!
The fw REST API is a licensed feature. Please contact sales@farmerswife.com for pricing information.
Also please provide us with info, of what you are planning to do with it. This helps us to assist with your onboarding of using the API.
Does the farmerswife support agreement also include API support?
No, it is not part of your normal farmerswife support agreement.
You can order "API 3rd party development consultancy" for us to assist you on getting onboarded or provide
3rd Party Integration consultancy and for purchased requests to enhance the fw REST API functionality, please
contact sales@farmerswife.com for more information.
1.1 License, support and development
1.2.2 Enabling GZip to compress HTTP responses
2. We use the "Postman" app and provide a "swagger.json" file
2.1 Requirements to use the fw REST API:
2.2 Supported resources and actions documentation - "swagger.json"
3. Best practice suggestions on working with Postman and the swagger.json file
3.1 Steps to Import the "swagger.json" file into Postman
3.2 Create your own static "auth" Collection
3.3 Create two "Variables" in Postman
3.4 Where the variable "baseUrl" is used
3.5 Where the variable "fwRESTapiToken" is used
1. Getting Started
The farmerswife (fw) REST API allows you to connect your own "application" to your fw Server to "read and query" (GET), "update or modify" (PUT) and "add or create" (POST) certain data, without having to use the fw end-user client interfaces (the fw Client desktop app on Mac and Windows), the native iOS fw app or Web/Mobile Client to access the system.
This page documents the currently available resources in the fwRESTapi, along with "JSON" schemas, expected HTTP response codes, and sample requests and responses. These are all contained within the below-mentioned "swagger.json" file.
1.1 License, support and development
The fw REST API is a licensed feature. Please contact sales@farmerswife.com or your Account Manager for a new license. The license will include a specific Application ID that will allow you to authenticate and interact with your fw Server via the fwRESTapi, in combination with the access credentials of an active and licensed user's Web Permission Profile, more info below.
IMPORTANT:
Using the fwRESTapi IS a "3rd party integration"!
Support in any form is not covered by active "Gold", "Silver" or "cloud hosted Premium" support agreements.
Each 3rd party integration is different.
To implement the integration 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 separately if needed, to facilitate limited 3rd-level technical support.
Potentially missing functionality is subject to purchased prioritized development.
To accomplish a smooth as possible integration experience, your integration goal(s) within farmerswife must be clearly defined.
This means the "Lead" farmerswife user e.g. builds a screen-shot storyboard from your farmerswife, 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 one important source for later troubleshooting and it will dramatically help us to assist you with your integration.
Please contact support@farmerswife.com to get a valid license before starting any kind of development.
1.2 Authentication
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 "fwRESTapi" user account you are using has the permissions needed on its Web Permission Profile for the actions you want to perform.
For instance, when editing the Web Permission Profile Settings (fw desktop Client app ▶ Object Manager ▶ Modify User ▶ Web Permission Profile):
- Limit users to only be able to create Timereports for themselves and not for other users; if you need to modify Timereports via the API, then the Web Permission Profile of the user used to access the API needs its own Web Permission Profile where this setting is not checked!:
- Timereports ▶ Not Other Users Time = Checked
- Give permissions to a user so they can create Projects via the API (both settings need to be enalbed/checked):
- Projects ▶ Show ▶ All Projects = Checked
- Projects ▶ Allow Editing Project ▶ Always = 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
{
"isError": 1,
"errorCode": 1022,
"description": "Expired or Illegal token.",
"timestamp": "2016-10-19T16:36:59+0200"
}In this case, you must handle the 401 Unauthorized exceptions and request a new access token.
1.2.2 Enabling GZip to compress HTTP responses
Optionally the fwRESTapi 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:
HTTP Header:
Fw-gzip-response: true
2. We use the "Postman" app and provide a "swagger.json" file
There are too many tools available to build integrations and our Development and Tech Support have chosen the "Postman" app as a single common tool for the best and fastest support for you.
All fw REST API changes are documented on our Release Notes (click here). You will find there all relevant "supported resources and actions documentation = swagger.json" versions and with which minimum farmerswife version they work together.
Even more helpful is using the "Supported resources and actions documentation - swagger.json" as described in the next chapter.
2.1 Requirements to use the fw REST API
- Download & Install Postman from https://www.getpostman.com
- If your fw_server is hosted by farmerswife, open Postman > go to Preferences > and check SSL setting:
- If DNS has this structure "clientName.farmerswife.com" --> set OFF SSL setting
- If DNS has this structure "clientName.cloud.farmerswife.com" --> set ON SSL setting
- Have a fw Server app running (ideally as a separate TEST environment) with a valid fw REST API appID within its license.
2.2 Supported resources and actions documentation - "swagger.json"
The fw REST API supports purchased and most requested resources and actions.
The available resources and actions are the ones described in the "Swagger JSON" technical documentation file.
Depending on the farmerswife version you have installed, you'll need a swagger.json file or another. Read our fwRESTApi Release Notes to get more information about improvements and bug g.
Find all the available versions of swagger.json at the bottom of this article.
- v0.8.19 - For customers on v7.1 or later.
- v0.8.11 - For customers on v7.0 or later.
- v0.8.9 - For customers on v6.8 Beta or later.
For viewing this "Swagger.json" file, we recommend just copying and pasting its contents into the online Swagger Editor: https://editor.swagger.io/
Once loaded into this viewer, this file tuns into an interactive "supported resources and actions documentation"!
The following screen-shot from the "Swagger.json" API Reference v0.8.19, is intended to provide a quick way to see all currently available resources supported by the fw REST API v1 (last updated 3-September-2024):
3. Best practice suggestions on working with Postman and the swagger.json file
You do not have to create an online account with Postman in order to work on your integration.
3.1 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 the "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.
,We keep expanding, changing and fixing the fw REST API. And for you to be able to use these latest changes you will need to keep importing the latest "swagger.json" file. This will always import the whole Collection of endpoints and action documentation. To avoid having to re-implement all need to changes to make this work, consider to setup your environment with this in mind.
After importing the swagger.json file the first time, use the "+" icon in Collections to create your own "fwRESTapi auth" collection. Then go to the auth/token endpoint and move by dragging and dropping the "POST" and "GET" endpoints to your own "auth" Collection.
Go to the auth/token POST endpoint in your own "auth" collection and on the "Body" tab and here update with the info you received from farmerswife support and according the the fw user you will be using to access the fwRESTapi. We recommend to use a dedicated "APIuser" for the integration, to avoid accidental Web Permission Profile changes, or when using Password Policies, to exclude this user from password expiry.
Go to the auth/token POST endpoint in your own "auth" collection and enter this code (Danke @F.Huster) into the "Test" pane to auto-populate the accessToken on all endpoints where this still to be created variable "fwTESTapiToken" has been set, more info below:
var data = JSON.parse(responseBody);
pm.environment.set("fwRESTapiToken", data.accessToken);
3.3 Create two "Variables" in Postman
To make it easier to work with the swagger.json fwRESTapi Collection(s) create two Global variables (some info used from here: https://learning.postman.com/docs/sending-requests/variables/):
To create and use a variable:
- Select the environment quick look icon
at the top right of Postman. - Next to Globals, select Edit.
- Add a first variable named "baseUrl" and enter: https://127.0.0.1:25000/api/v1
This configuration assumes that the fw Server app is running on the same computer as Postman AND if e.g. the "DemoDB" is being used, or/and the "API Port" in fw Server > Setup > General > API Port is set to 25000.
NOTE: If the fw Server app is running on a different machine, or is being cloud hosted by us the "baseUrl" info will be different!
For self-hosted fw Server apps, see more info here: Server Ports and Access Tiers on "Url To Server" and "API Port".
And for fw-cloud farmerswife systems, the complete Access Details will be handed over, when the fwRESTapi gets licensed. - Add a second variable named "fwRESTapiToken".
- Select
Save, then close the environment tab.
3.4 Where the variable "baseUrl" is used
When importing the fwRESTapi swgger.json file, the variable is already set and used on every endpoint:
3.5 Where the variable "fwRESTapiToken" is used
This gets used on almost all endpoints on the "Authorization" tab on the "Value" field, by pre-pending "Bearer" in this format: Bearer {{fwRESTapiToken}}
Use the auth/token POST endpoint > "Send" button to get your first AccessToken.
The response should be similar to this:
{"isError":0,"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...You can also use the auth/token GET endpoint > "Send" button to verify, that you have configured everything correctly and you can access the fwRESTapi; ensure you have set on the Authorization > Value the needed "Bearer {{fwRESTapiToken}}".
4. Logging
We improved the REST Api log file in `/system/customlog.restapi.log` based on a new server.cfg var `HTTP_REST_LOG_LEVEL` (1 = ON), with request duration in milliseconds, http method, url with GET params, and a transaction id value for traceability in log lines. Also logging internal server/unexpected errors.