farmerswife

Welcome
Login  Sign up

The farmerswife Server's REST API - for your own 3rd party integrations

Last updated: 9-August-2019 

This article  contains all MUST HAVE items for a successful integration. 


See the latest fw REST API changes on these Release Notes:

=> 6.5 Beta 6

=> 6.5 Beta 7


To get the latest documentation see below this section "1.5 Supported resources and actions documentation"


(NOTE: In case your are still using this legacy link to the OLD documentation, this is by now obsolete and will be deactivated soon: https://farmerswife.atlassian.net/wiki/spaces/devnotes/pages/71991367/REST+API)


REST API Version 1


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 to access the system: fw Client Desktop app, iOS fw app or Web/Mobile Client.


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.


1.1 License

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 6.5 Beta 6 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 support@farmerswife.com to get a valid license before starting 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 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 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 credentials you are using, actually has the according and needed Web Permission Profile Settings in the system for the actions you want to perform. 

For instance: 

  • If fw desktop Client ▶ Object Manager ▶ Edit User ▶ Web Profile ▶ Timereports ▶ "Not Other Users Time" is off or not enabled, then you will only be able to create time-reports for this "fw REST API" user and not for the other users.
  • Or if you need to create Projects via the fw REST API, then the Web Permission Profile requires these two settings to be active and not limited via fw desktop Client ▶ Object Manager ▶ Edit User ▶ Web Profile ▶ Projects ... 
    ▶ Show ▶ All Projects
    ... and:
    ▶ Allow Editing Project ▶ Always


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

{

    "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 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:

HTTP Header:

Fw-gzip-response: true


1.4 How to import the Postman Collection to Postman for a quick start

Requirements:

  • 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 appID and license.

Steps to Import into Postman:

  • Attached to this page you have the following Postman Collection that you can import to Postman: Postman_Collection.zip (<= 22-May-2019 still pending to be updated!)
  • Decompress the Postman_Collection.zip file into a folder of your choice
  • Open Postman > Import > Import File and drag and drop it or select the folder containing the Postman Collection.


1.5 Supported resources and actions documentation

At the moment, the fw REST API only supports some resources and actions.

All available resources and actions are the ones described in this "Swagger Json" file (v0.5, last updated 17-June-2019 in sync with changes up to 6.5 Beta 7): 


fw REST API supported resources and actions file download 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/


Screenshot from the "Swagger" Api Reference v0.5, to quickly see the available resources that are currently supported by the fw v6.5 Beta REST API (last updated 17-June-2019):


Did you find it helpful? Yes No