{"swagger":"2.0","info":{"title":"AB Agri Data Insights","description":"","version":"1.0.0"},"host":"abagri-nv-link-api-dev.azurewebsites.net","basePath":"/api","schemes":["https"],"tags":[{"name":"Farms"},{"name":"Jobs"},{"name":"User"},{"name":"KPIs"}],"consumes":["application/json"],"produces":["application/json"],"securityDefinitions":{"OAuth2":{"type":"oauth2","authorizationUrl":"https://oauth.example.com","tokenUrl":"https://exampleTokenPath.com","flow":"accessCode","scopes":{}}},"security":[{"OAuth2":[]}],"paths":{"/farms":{"get":{"tags":["Farms"],"operationId":"GetFarms","description":"Retrieves all the farms ( within the bounds of the filters ), available to the authenticated user","parameters":[{"name":"pageSize","in":"query","type":"integer","format":"int32","default":10,"description":"The number of records per page being requested. Default 10"},{"name":"pageNumber","in":"query","type":"integer","format":"int32","minimum":1,"description":"The page being requested. Default 1"},{"name":"order","in":"query","type":"string","default":"az","enum":["az","za","lastUpdated"],"description":"Reorder the list using the enum values, default az (A-Z)"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/farmSearch"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/farms/{farmId}/kpis":{"get":{"tags":["KPIs","Farms"],"operationId":"GetFarmKpiByFarmId","description":"Retrieves the KPIs for a Farm","parameters":[{"name":"farmId","in":"path","type":"string","required":true,"description":"The farmId"}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/farmKpis"}},"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/jobs":{"get":{"tags":["Jobs"],"operationId":"GetJobs","description":"Retrieves all jobs","parameters":[{"name":"pageSize","in":"query","type":"integer","format":"int32","default":10,"description":"The number of records per page being requested. Default 10"},{"name":"pageNumber","in":"query","type":"integer","format":"int32","minimum":1,"description":"The page being requested."},{"name":"order","in":"query","type":"string","description":"Reorder the list using the enum values, default DateTimeDesc","default":"DateTimeDesc","enum":["DateTimeAsc","DateTimeDesc","AgeAsc","AgeDesc"]}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/jobsSearch"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/jobs/farm/{farmId}":{"get":{"tags":["Jobs"],"operationId":"GetJobsByFarmId","description":"Retrieves all jobs for a certain farm","parameters":[{"name":"farmId","in":"path","type":"string","required":true},{"name":"pageSize","in":"query","type":"integer","format":"int32","default":10,"description":"The number of records per page being requested. Default 10"},{"name":"pageNumber","in":"query","type":"integer","format":"int32","minimum":1,"description":"The page being requested."},{"name":"order","in":"query","type":"string","description":"Reorder the list using the enum values, default DateTimeDesc","default":"DateTimeDesc","enum":["DateTimeAsc","DateTimeDesc","AgeAsc","AgeDesc"]}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/jobsSearch"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/jobs/farm/{farmId}/{status}":{"get":{"tags":["Jobs"],"operationId":"GetJobsByFarmIdAndStatus","description":"Retrieves all available jobs of a certain Farm, with a given status","parameters":[{"name":"farmId","in":"path","type":"string","required":true},{"name":"status","in":"path","type":"string","required":true},{"name":"pageSize","in":"query","type":"integer","format":"int32","default":10,"description":"The number of records per page being requested. Default 10"},{"name":"pageNumber","in":"query","type":"integer","format":"int32","minimum":1,"description":"The page being requested."},{"name":"order","in":"query","type":"string","description":"Reorder the list using the enum values, default DateTimeDesc","default":"DateTimeDesc","enum":["DateTimeAsc","DateTimeDesc","AgeAsc","AgeDesc"]}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/jobsSearch"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/jobs/status/{status}":{"get":{"tags":["Jobs"],"operationId":"GetJobsByStatus","description":"Retrieves all available jobs with a given status","parameters":[{"name":"status","in":"path","type":"string","required":true},{"name":"pageSize","in":"query","type":"integer","format":"int32","default":10,"description":"The number of records per page being requested. Default 10"},{"name":"pageNumber","in":"query","type":"integer","format":"int32","minimum":1,"description":"The page being requested."},{"name":"order","in":"query","type":"string","description":"Reorder the list using the enum values, default DateTimeDesc","default":"DateTimeDesc","enum":["DateTimeAsc","DateTimeDesc","AgeAsc","AgeDesc"]}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/jobsSearch"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/jobs/{jobId}":{"get":{"tags":["Jobs"],"operationId":"GetJobByJobId","description":"Retrives a job using its unique identifier","parameters":[{"name":"jobId","in":"path","type":"string","description":"The unique job identifier: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","required":true}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/jobDetail"}},"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}},"post":{"tags":["Jobs"],"operationId":"PostJobUsingJobId","description":"Adds a comment or/and edits the status of insights for a job","parameters":[{"name":"jobId","in":"path","type":"string","description":"The unique job identifier: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX ","required":true},{"in":"body","name":"body","schema":{"$ref":"#/definitions/jobAction"}}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/user":{"get":{"tags":["User"],"operationId":"GetAuthenticatedUserDetails","description":"Retrieve the details of the authenticated user","parameters":[],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/user"}},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}},"post":{"tags":["User"],"operationId":"PostAuthenticatedUserDetails","description":"Updates/Adds the details of the authenticated user","parameters":[{"in":"body","name":"body","schema":{"$ref":"#/definitions/user"},"required":true}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}},"/notifications":{"post":{"tags":["User"],"operationId":"PostRegisterDeviceForNotifications","description":"A call that passes a platform specific handle in order to register a device with the notification service","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/postNotificationsBody"}}],"responses":{"200":{"description":"Ok","schema":{"$ref":"#/definitions/notificationRegisterResponse"}},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}},"put":{"tags":["User"],"operationId":"PutUpdateDeviceForNotifications","description":"A call that passes a platform specific handle, the paltform type and the notification hub registration id in order to update the registeration of a device with the notification service","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/putNotificationsBody"}}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"410":{"$ref":"#/responses/410"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}},"delete":{"tags":["User"],"operationId":"DeleteDeviceFromNotifications","description":"A delete call that passes the registration id in order to deregister a device with the notification service","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/deleteNotificationsBody"}}],"responses":{"204":{"$ref":"#/responses/204"},"400":{"$ref":"#/responses/400"},"401":{"$ref":"#/responses/401"},"404":{"$ref":"#/responses/404"},"429":{"$ref":"#/responses/429"},"500":{"$ref":"#/responses/500"},"503":{"$ref":"#/responses/503"}}}}},"responses":{"204":{"description":"No Content"},"400":{"description":"Malformed request","schema":{"$ref":"#/definitions/apiError"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/apiError"}},"403":{"description":"Forbidden","schema":{"$ref":"#/definitions/apiError"}},"404":{"description":"The resource does not exist","schema":{"$ref":"#/definitions/apiError"}},"410":{"description":"The requested resource is no longer available at the server and no forwarding address is known.","schema":{"$ref":"#/definitions/apiError"}},"429":{"description":"Too many requests","schema":{"$ref":"#/definitions/apiError"}},"500":{"description":"Server error","schema":{"$ref":"#/definitions/apiError"}},"503":{"description":"Maintenance","schema":{"$ref":"#/definitions/apiError"}}},"parameters":{},"definitions":{"farmSearch":{"required":["pageSize","pageSizeMax","pageNumber","totalRecords","order","farms"],"properties":{"pageSize":{"type":"integer","format":"int32","description":"The number of records per page being returned. Default 10.","default":10},"pageSizeMax":{"type":"integer","format":"int32","description":"The maximum number of items that can be requestd in a single response."},"pageNumber":{"type":"integer","format":"int32","description":"The page number being requested. Default 1.","default":1},"totalRecords":{"type":"integer","format":"int32","description":"The total number of records in available."},"order":{"type":"string","description":"The order in which the results are being returned. Default az (A-Z)","default":"az","enum":["az","za","distance","lastUpdated"]},"farms":{"$ref":"#/definitions/farms"}}},"farms":{"type":"array","description":"A list of farms available to the account","items":{"$ref":"#/definitions/farm"}},"farm":{"type":"object","description":"Properties of the farm","required":["farmId","lastUpdate","lastSync","name","address","contact","latestJobCount"],"properties":{"farmId":{"type":"string","format":"uuid","description":"Unique identifier for each farm. The format will vary"},"lastUpdate":{"type":"string","format":"date-time","description":"!IMPORTANT: This field needs to be updated EVERY TIME something within the farm CHANGES ( this includes jobs, insights, comments, kpis, and any other data that can change state ) !!! This is going to be used to check data for sync purposes"},"name":{"type":"string","description":"Name of the farm."},"latestJobCount":{"type":"integer","format":"int32","description":"The count of the latest jobs raised accross all houses or groups"},"address":{"$ref":"#/definitions/address"},"contact":{"$ref":"#/definitions/contact"},"houses":{"type":"array","description":"Array of houses on the farm. Poultry only.","items":{"$ref":"#/definitions/house"}},"groups":{"type":"array","description":"Array of groups on the farm. Dairy only.","items":{"$ref":"#/definitions/group"}},"lastSync":{"type":"string","format":"date-time","description":"Date-time when the API data last synchornized with any of the the farm's sensors"}}},"house":{"type":"object","required":["id","houseNumber","houseName","houseCap"],"properties":{"id":{"description":"Poultry only: Unique ID of the house","type":"string","format":"uuid"},"houseNumber":{"description":"Poultry only: Unique Number of the house within farm.","type":"integer","format":"int32"},"houseName":{"type":"string","description":"Poultry only: Name of house will be House <housenumber>"},"houseCap":{"type":"integer","format":"int32","description":"Poultry only: Capacity of the house, maximum number of chicks in a crop."}}},"group":{"type":"object","required":["id","dtmPenId","penName","penType","penSubType"],"properties":{"id":{"type":"string","description":"Dairy only: Unique ID of the group","format":"uuid"},"dtmPenId":{"type":"integer","format":"int32","description":"Dairy only: Unique ID of the group within farm."},"penName":{"type":"string","description":"Dairy only: Current name of the pen."},"penType":{"type":"string","description":"Dairy only: Current enterprise category of pen (e.g. Milkers, Dry Cow, Young Stock and Heifers) This type is important when comparing feed patterns and results across farms."},"penSubType":{"type":"string","description":"Dairy only: Current sub type of the pen type. E.g. For Milkers we could have High Yield & Low Yield."}}},"contact":{"type":"object","required":["email","phone","firstName","lastName"],"description":"Contact details","properties":{"firstName":{"type":"string","description":"The farmers first name"},"lastName":{"type":"string","description":"The farmers last name"},"email":{"type":"string","format":"email","description":"Default email for the farm. This can be different from the users logon email address."},"phone":{"type":"string","format":"phone","description":"Main phone for the farm (international dialling codes included)"}}},"jobsSearch":{"required":["pageSize","pageSizeMax","pageNumber","totalRecords","order","jobs"],"properties":{"pageSize":{"type":"integer","format":"int32","description":"The number of records per page being returned. Default 10."},"pageSizeMax":{"type":"integer","format":"int32","description":"The maximum number of items that can be requestd in a single response."},"pageNumber":{"type":"integer","format":"int32","description":"The page number being requested. Default 1."},"totalRecords":{"type":"integer","format":"int32","description":"The total number of records in available."},"order":{"type":"string","description":"Reorder the list using the enum values, default DateTimeDesc","default":"DateTimeDesc","enum":["DateTimeAsc","DateTimeDesc","AgeAsc","AgeDesc"]},"jobs":{"$ref":"#/definitions/jobs"}}},"jobs":{"type":"array","description":"An array of job summaries","items":{"$ref":"#/definitions/jobSummary"}},"jobSummary":{"type":"object","required":["id","sourceId","lastUpdate","farmId","categories","status","dateApplies"],"description":"Main properties of a Job","properties":{"id":{"type":"string","description":"Unique identifier for the job. Same that gets passed in the query string as a parameter.","format":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"lastUpdate":{"type":"string","format":"date-time","description":"ISO 8601 dates"},"farmId":{"type":"string","description":"Unique identifier for farm","format":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"sourceId":{"type":"string","description":"Unique identifier for house/group","format":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"age":{"type":"integer","format":"int32","description":"Age of the crop. The is the number of days from datePlaced. (nullable)"},"dateApplies":{"type":"string","format":"date-time","description":"ISO 8601 dates (local) - Date of the job"},"categories":{"$ref":"#/definitions/categoryInsights"},"status":{"type":"string","description":"Possible status for a job is either Open or Closed","enum":["Open","Closed"]}}},"categoryInsights":{"type":"array","items":{"$ref":"#/definitions/categoryInsight"},"description":"List of current category alerts"},"categoryInsight":{"type":"string","description":"Type of insight. There are 4 categories for poultry (water, weight, mortality & temperature). There are 2 for dairy (Dry matter intake & Yield).","enum":["Water","Weight","Mortality","Temperature","DryMatterIntake","Yield"]},"jobDetail":{"type":"object","description":"All of a job's properties","required":["id","lastUpdate","farmId","type","sourceId","cropDate","datePlaced","dateApplies","status","categories"],"properties":{"id":{"type":"string","description":"Unique identifier for the job. Same that gets passed in the query string as a parameter.","format":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"},"lastUpdate":{"type":"string","format":"date-time","description":"ISO 8601 dates"},"farmId":{"type":"string","description":"Unique identifier for farm"},"type":{"type":"string","description":"Animal/process type."},"sourceId":{"type":"string","description":"Unique identifier for crop source. (eg. house id or group id)"},"cropDate":{"type":"string","format":"date-time","description":"Date at the start of the crop. ISO 8601 date"},"datePlaced":{"type":"string","format":"date-time","description":"ISO 8601 date. Date the animals were placed in the house. Note this could be different to the cropdate. For example 2 houses may have the same cropdate but the chick were put into the second house a day later. The age is calculated from this value. "},"dateApplies":{"type":"string","format":"date-time","description":"ISO 8601 dates (local) - Date of the job"},"age":{"type":"integer","format":"int32","description":"Age of the crop. The is the number of days from datePlaced. (nullable)"},"categories":{"$ref":"#/definitions/jobCategories"},"status":{"description":"Status of job. Either Open or Closed","type":"string","enum":["Open","Closed"]}}},"jobCategories":{"type":"array","description":"List of job categories","items":{"$ref":"#/definitions/jobCategory"}},"jobCategory":{"type":"object","required":["insights","category"],"properties":{"insights":{"$ref":"#/definitions/insights"},"comment":{"type":"array","description":"A list of comments grouped by category","maxLength":255,"items":{"$ref":"#/definitions/comment"}},"category":{"$ref":"#/definitions/categoryInsight"}}},"insights":{"type":"array","description":"List of insights","items":{"$ref":"#/definitions/insight"}},"kpis":{"type":"array","items":{"$ref":"#/definitions/kpi"},"description":"List of KPIs for this farm"},"kpi":{"type":"object","required":["url","name","value","unit","benchmarkPosition","lastValue"],"properties":{"url":{"type":"string","description":"URL to the website where nore details about the record and it's history can be found. Likley to be null"},"name":{"type":"string","description":"A descriptive name of the KPI a user will recognise"},"value":{"type":"string","description":"The value of the KPI"},"unit":{"type":"string","description":"The unit associated with the KPI"},"benchmarkPosition":{"type":"string","enum":["Top","Average","Bottom"],"description":"An enum to show the comparison against other farms in the defined area"},"lastValue":{"type":"string","description":"The value that was previously returned in the KPI value response."}}},"insight":{"type":"object","required":["insightId","triggerReason","status","description"],"properties":{"insightId":{"type":"string","description":"Unique identifier for the insight"},"triggerReason":{"type":"array","items":{"description":"Description of the potential cause of the insight","type":"string"},"description":"As the Expert System evaluates each category, the Triggers identify why a Job has been raised within a category. There can be multiple triggers within a Category some of which will call the same insight."},"description":{"type":"string","description":"The description is the suggested reason/action to be taken based on the outputs of the Expert System. There will be multiple insights within a Job which suggest what the user should check/do. We expect the user to then identify which of the insights was valid for that day"},"status":{"type":"string","description":"Current status of the insight","enum":["Ignored","Actioned","NoAction"]}}},"user":{"type":"object","description":"Authenticated user's details","required":["notificationsEnabled"],"properties":{"notificationsEnabled":{"type":"boolean","description":"Are notifications currently enabled"}}},"comment":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","description":"The Comments are for the user to enter another reason for the Job which does not appear in the Insights list. This may be a practical on farm event which was not captured in the data."},"createdAt":{"type":"string","format":"date-time","description":" ISO 8601 date representing the last update"}}},"address":{"description":"Full farm address","required":["postcode","country","address1","address2","address3","address4"],"properties":{"postcode":{"type":"string","description":"Postcode of the farm location"},"country":{"type":"string","description":"Country of the farm"},"address1":{"type":"string","description":"1st address line"},"address2":{"type":"string","description":"2nd address line"},"address3":{"type":"string","description":"3rd address line"},"address4":{"type":"string","description":"4th address line"}},"type":"object"},"jobAction":{"type":"object","required":["status","categories"],"properties":{"status":{"type":"string","description":"The status update for the job","enum":["Closed"]},"categories":{"type":"array","description":"A collection of insights to be updated","items":{"$ref":"#/definitions/categoryUpdate"}}}},"categoryUpdate":{"type":"object","required":["insightUpdates","comment"],"properties":{"category":{"$ref":"#/definitions/categoryInsight"},"comment":{"$ref":"#/definitions/comment"},"insightUpdates":{"type":"array","items":{"$ref":"#/definitions/insightUpdate"}}}},"insightUpdate":{"type":"object","properties":{"insightid":{"type":"string"},"action":{"type":"string","enum":["NotValidated","Invalid","Valid"],"description":"The action taken by the farmer for the specific job"}}},"farmKpis":{"type":"object","description":"an object representing the details of a farm's Kpis","required":["frequency","kpis","lastUpdate","benchmarkRegion"],"properties":{"lastUpdate":{"type":"string","format":"date-time","description":" ISO 8601 date representing the last update"},"frequency":{"type":"integer","format":"int32","description":"The frequency in days that the data is updated"},"benchmarkRegion":{"type":"string","description":"Describes the population of the kpis. Can specify a geographical region or a certain type of source/product"},"kpis":{"$ref":"#/definitions/kpis"}}},"putNotificationsBody":{"type":"object","required":["pnsHandle","platform","notificationHubRegistrationId"],"properties":{"pnsHandle":{"type":"string","description":"The pnsHandle returned from platform specific push notification"},"platform":{"type":"string","description":" ","enum":["apns","gcm"]},"notificationHubRegistrationId":{"type":"string","description":"The notification hub registration id"}}},"postNotificationsBody":{"type":"object","required":["pnsHandle","platform","notificationHubRegistrationId"],"properties":{"pnsHandle":{"type":"string","description":"The pnsHandle returned from platform specific push notification"}}},"deleteNotificationsBody":{"type":"object","required":["notificationHubRegistrationId"],"properties":{"notificationHubRegistrationId":{"type":"string","description":"The notification hub registration id"}}},"notificationRegisterResponse":{"type":"object","properties":{"notificationHubRegistrationId":{"type":"string"}}},"apiError":{"type":"object","required":["errors"],"description":"Possible error collection with details returned by the API on a call","properties":{"errors":{"$ref":"#/definitions/errors"}}},"errors":{"type":"array","description":"A list of errors","items":{"$ref":"#/definitions/error"}},"error":{"type":"object","required":["errorType","description"],"properties":{"errorType":{"type":"string","description":"An error code to provide more detail on what went wrong with the request","enum":["FieldIncorrect","QuerystringPropertyMising","...Fill this list in"]},"description":{"type":"string","description":"description of the error being returned."}}}}}