Gardening Projects API

The Gardening Project

The ET Unity service considers a Gardening Project a canvas for all vegetation, irrigation zones, and landscape related information. Consider the Project as the site or address that contains all the plants and landscape details. After having created an account, the project would be the next step to create, as every environmental datapoint, from plants to weather to soil specifics, requires a Project to relate to. Although technically not a requirement, Projects typically refer to one physical location, and are recommended to be used as one location per project.

How to create a project

Creating a Project is really easy. All it takes is a simple HTTP call with an empty JSON object using the [html]POST[/html] method to [html]https://developer-api.etwater.com/api/v1/gardening/projects[/html]. As we’re going to send data to the server, we need to specify what kind of data we’re sending using the [html]Content-Type[/html] HTTP header. In our case the content type should be [html]application/json[/html]. As all calls should include your access token, make sure to replace [html]$ACCESS_TOKEN[/html] in the below examples with your access token.

cURL request example

Here is how you’d make the call using cURL:

[json]curl -XPOST -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects' -d '{}'[/json]

Response example

And here is what you’d get back from the Unity API:

[json]{
	"name": "Buena Vista Park,SF",
	"created_at": 1475067523039,
	"updated_at": 1475068440090,
	"version": 4,
	"postal_code": "94117",
	"location": {
		"type": "Point",
		"coordinates": [
			-122.4410896675,
			 37.768361565
		]
	},
	"id": "57ebbe830e8e3d000155552e"
}
[/json]

The [html]ID[/html] is the unique identifier for the Project. You’ll use this ID in al your calls related to this Project. The [html]created_at[/html] and [html]updated_at[/html] are both timestamps in the EPOCH with milliseconds format (milliseconds since January 1, 1970). The [html]version[/html] number increments each time the project is updated. You can use this to track changes and keep projects in sync across multiple devices that are logged on simultaneously.

POSTMAN request and response example

If you’re using Postman, here is what that would look like. First make sure you enter your headers:

Then make your call and see the response:

How to update a project

Whenever you need to update the project you should use the [html]PUT[/html] method and call [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}[/html]. Where [html]projectId[/html] is the [html]ID[/html] of a project you’d like to update. Here too we need to specify what kind of data we’re sending using the [html]Content-Type[/html] HTTP header [html]application/json[/html].

cURL request example

[json]curl -XPUT -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ebbe830e8e3d000155552e' -d '{"name": "Buena Vista Park,SF"}'
[/json]

Response example

[json]{
	"name": "Buena Vista Park,SF",
	"created_at": 1475067523039,
	"updated_at": 1475068440090,
	"version": 4,
	"postal_code": "94117",
	"location": {
		"type": "Point",
		"coordinates": [
			-122.4410896675,
			37.768361565
		]
	},
	"id": "57ebbe830e8e3d000155552e"
}
[/json]

When updating a project you should only pass the fields you want to change, and remember that not all of the field can be changed (for instance, the [html]ID[/html] field can’t be changed in any entity available through the Unity API).

POSTMAN request and response example

Using POSTMAN, first set your headers:

And then send your request:

How to delete a project

To delete a project you should perform an HTTP call to [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}[/html] using [html]DELETE[/html] HTTP method, where [html]projectId[/html] is the ID of the project you’d like to delete.

Note: Deleting the project will delete all associated regions, zones, parcels and other data too. Be careful what you do here.

cURL request example

[json]curl -XDELETE -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ebc4490e8e3d0001555538'
[/json]

For this call the server doesn’t return anything except a 204 HTTP status code. To see that code you should add `-v` for verbose output to the cURL command options:

cURL request example with verbose output

[json]curl -v -XDELETE -H'Authorization: Bearer $ACCESS_TOKEN' -H'Content-Type: application/json' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ebc4490e8e3d0001555538'
[/json]

Verbose response example

[html]*   Trying 54.230.230.22...
* Connected to developer-api.etwater.com (54.230.230.22) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate: *.etwater.com
* Server certificate: COMODO RSA Domain Validation Secure Server CA
* Server certificate: COMODO RSA Certification Authority
* Server certificate: AddTrust External CA Root
> DELETE /api/v1/gardening/projects/57ebc4490e8e3d0001555538 HTTP/1.1
> Host: developer-api.etwater.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
>
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< Date: Wed, 28 Sep 2016 13:32:43 GMT
< Access-Control-Allow-Origin: *
< x-amzn-RequestId: 08932e04-8580-11e6-b7f9-a54d41f992da
< X-Cache: Miss from cloudfront
< Via: 1.1 0e6067b46ed4b3e688f898d03e5c1c67.cloudfront.net (CloudFront)
< X-Amz-Cf-Id: d4UnwAxMOYop4bWY9Zs14j6G6rl8XIiCTKNsYHVfnjMxUe3Ln_meGw==
<
* Connection #0 to host developer-api.etwater.com left intact
* 
[/html]

The important line here is [html]HTTP/1.1 204 No Content[/html] which indicates that the server processed the request but returned no content in the response.

POSTMAN request and response example

Note the red arrow pointing to where you will see the response status.

How to get one specific project

To get one particular project you should call [html]https://developer-api.etwater.com/api/v1/gardening/projects/{projectId}[/html] using the [html]GET[/html] HTTP method, where [html]projectId[/html] is the [html]id[/html] of the project you’d like to get.

cURL request example

[json]curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/gardening/projects/57ebbe830e8e3d000155552e'
[/json]

Response example

[json]{
	"name": "Buena Vista Park",
	"created_at": 1475067523039,
	"updated_at": 1475067565420,
	"version": 2,
	"postal_code": "94117",
	"location": {
		"type": "Point",
		"coordinates": [
			-122.4410896675,
	 	 	 37.768361565
		]
	},
	"id": "57ebbe830e8e3d000155552e"
}
[/json]

The response contains everything for the one specific project we asked for.

POSTMAN request and response example

How to get all your projects

To get all your projects you need to perform a call to [html]https://developer-api.etwater.com/api/v1/gardening/projects[/html] using the [html]GET[/html] HTTP method.

cURL request example

[json]curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/gardening/projects'
[/json]

Response example

[json]
[
	{
		"name": "Buena Vista Park",
		"created_at": 1475067523039,
		"updated_at": 1475067565420,
		"version": 2,
		"postal_code": "94117",
		"location": {
			"type": "Point",
			"coordinates": [
				-122.4410896675,
				37.768361565
			]
		},
		"id": "57ebbe830e8e3d000155552e"
	}
]
[/json]

The response will contain a list of your projects.

POSTMAN request and response example

 
©2016 ETwater. All rights reserved. Privacy Information. SMART OUTDOORS® and WELCOME TO THE SMART OUTDOORS® are registered trademarks of ET Water Systems, Inc.