Registering Watchers
There are two ways to register watchers in Noah:
- Web API
- Ruby API
Registering a new watcher via the web API is as simple as appending /watch to the end of an existing API url in a PUT message:
$ curl -XPUT -d'{"name":"my_sexy_application"}' http://localhost:5678/a/my_sexy_application
{"result":"success","id":"2","action":"create","name":"my_sexy_application"}
$ curl -XPUT -d'{"endpoint":"http://localhost:3000/webhook"}' http://localhost:5678/a/my_sexy_application/watch
"Ly9ub2FoL2FwcGxpY2F0aW9uL215X3NleHlfYXBwbGljYXRpb258aHR0cDovL2xvY2FsaG9zdDozMDAwL3dlYmhvb2s="
When you create a watch, this way, you are sent back a Base64 string that maps to the following:
"//noah/watch/pattern|callback_url"
In the above example, our Base64 key translates to: "//noah/application/my_sexy_application|http://localhost:3000/webhook"
Alternately, you can register watches via the /w/ endpoint. This is useful if you want to cast a broader net for watches (i.e. //noah/application as opposed to a specific application:
$ curl -XPUT -d'{"pattern":"//noah/application","endpoint":"http://localhost:3001/webhook"}' http://localhost:5678/w/
{"action":"create","result":"success","id":"8","pattern":"//noah/application","name":"Ly9ub2FoL2FwcGxpY2F0aW9ufGh0dHA6Ly9sb2NhbGhvc3Q6MzAwMS93ZWJob29r","endpoint":"http://localhost:3001/webhook","created_at":"2011-03-15 11:17:52 UTC","updated_at":"2011-03-15 11:17:52 UTC"}
There are a few restrictions on watchers for now that must be taken into account:
- Watchers cannot be updated, only created and deleted
- Watchers are unique per pattern/endpoint combination
- You cannot create a watch for a given endpoint that be a superset/subset of an existing watch for that endpoint.
These policies exist to prevent any duplication of messages. The last one is very important. Let's assume our initially created watch on //noah/application/my_sexy_application.
If we were to create a second watch using the same endpoint but having a pattern of //noah/application/, our endpoint would see duplicate messages for operations against my_sexy_application - once for the absolute path and once for the parent path. Alternately, assuming we set our watch for //noah/application and wanted to add more specific watch for //noah/application/my_sexy_application, that would be rejected as well for the same reasons - duplicate callbacks.
The following error responses are sent in the above situations:
{"result":"failure","error_message":"Record already exists"}
{"result":"failure","error_message":"Pattern would overwrite existing"}
{"result":"failure","error_message":"Pattern is already provided"}
Additionally, no validation is done currently at watch creation time if a path is no longer valid. Should we delete my_sexy_application, a delete message will be sent to all registered watchers but the watch itself would not be deleted.
Each model has a watch! method associated with it. Simply call that method with a hash containing the endpoint and the watch will be created:
a = Noah::Application.new
a.name = "wicked_application_rocks"
a.save
#<Noah::Application:3 created_at="2011-03-15 11:30:33 UTC" updated_at="2011-03-15 11:30:33 UTC" name="wicked_application_rocks">
a.watch! :endpoint => "http://localhost:3003/webhook"
"Ly9ub2FoL2FwcGxpY2F0aW9uL3dpY2tlZF9hcHBsaWNhdGlvbl9yb2Nrc3xodHRwOi8vbG9jYWxob3N0OjMwMDMvd2ViaG9vaw=="
The same constraints as above apply.