API Changes

[zac]

The API now accepts "add" over POST. "verify" only works on GET.

[balu]

Thanks for this push api

only one question left,
what does the priority int do ?

[jacobb]

I believe right now it does nothing as far as the server is concerned--but it's a variable passed by growl and stored, and could be used down the line (New style for high priority items, server-side filtering based on it), so probably best to store it for legacy pushes.

Zac can post and completely prove me wrong though.

Prowlpy is updated to use POST, fwiw.

[zac]

Right now it does nothing. In the future it will determine delivery, etc., of notifications and other display things.

[zac]

Added a note about API limits: 1000 per hour per IP address. Contact me if you need to exceed this limit.

This also adds the key "providerkey" and an API error response code for exceeding the limit. The successful update stanza has been updated for new API limit data.

[snkhan]

Wow, that limit is quite generous. Wondered whether it might be worthwhile creating a thead containing sample code? It looks as if we have a Perl and PHP solution in this thread.

[zac]

The limit might be reduced to something like 500 over time, but not much less than that. I don't want to even come within danger of impacting normal use.

The FAQ has a few libraries too: http://prowl.weks.net/faq.php#script - I'll be creating an API section on the website, soon, with more detail.

[ideoplex]

And for the command-line user/shell-scripter with a curl executable (http://curl.haxx.se/)

Code: Select all

curl https://prowl.weks.net/publicapi/add -F apikey=xxx -F application=curl -F event='Ta Da' -F description='Here We Go'

I believe you mean "add" instead of "get".

Whoops, I stand corrected. I've also removed the -k as a real certificate has been installed.

[zac]

I believe you mean "add" instead of "get".

[Fenric]

At this moment in time it seems to verify your API key to begin with counts as an API request and deducts one from your remaining amount. As verifying a key doesn't actually send anything to Apple (though it of course involves the Prowl server doing some work) is this something that will stick around or will the request limit be for just actual push requests? I'm defiantly not complaining and the limit is incredibly generous, I just wondered. ^_^

Also, quick question with regards to provider keys. If you supply a provider key, is the original API key required to be sent with the request?

Cheers!

[zac]

Verify should be used to confirm an API key is valid, but only used once (when the user enters it into a service, etc). The "invalid API key" response occurs when a push notification is attempted and the API key is invalid, so the verify is just an additional (unnecessary) call.

A provider key only increases the available API class for the calls which use the provider key, so yes the API key is absolutely required or it wouldn't have a user to send to!

[Fenric]

Lol, no no I wasn't asking if verify was required, it most defiantly is. It's just the API remaining requests amount is decreased by one when you call verify and then another for each push that is requested. I just wondered, and thinking about it now it was a silly question, but considering the verify request doesn't actually send anything to Apples push notification servers should it lower the remaining count. Each time you want to send a notification is counts as 2 requests, so a limit of 1000 isn't actually 1000 notifications but potentially only 500. However, the limit is more than generous already and the count is, as described, the remaining API requests, your server is still doing some work to verify the api key, so I've really just answered my own question. Sorry to be a pain!

Cool, thanks for the info on provider keys, wasn't 100% sure how to implement it.

[zac]

What I mean to say is, it's not necessary to call verify for every push. If you're accepting user entered keys, verify them when entering. Otherwise just push with the key, you'll get the appropriate error if it's invalid. Look at the note below verify on the first post.

[Fenric]

Oh right! My apologies, I had missed that bit. Thank you!

[ehunt123]

Would it be possible to setup an RSS feed for the API/new client versions/new plugins? Thanks

[zac]

If you've hard-coded the Prowl IP address into any of your scripts, it is going to break soon as the forward-facing IP address is changing (and may become part of a pool of addresses). You should use the hostname (prowl.weks.net) for looking up connections to the server.

[zac]

You can now provide up to 5 API keys in a single call, see the API page for documentation.

[caseywatson]

I just wanted to drop a quick post to let you guys know that I just pushed an open-source .NET library to http://prowldotnet.codeplex.com/ that allows you to access the Prowl API from C#, VB.NET, etc. Enjoy. Share.

[erazer]

I spend over an hour figuring out what was wrong with my add POST..

The normal way to do a HTTP POST, is to include the posted data (arguments) into the body, not the URL...
I don't think it's mentioned that altough it's a HTTP POST, the data should be in the URL itself...

Anyway, this is the first iphone app I paid for, damn this is cool!

[zac]

Removed the 5 limit on multiple API key messages. There is now no limit.