API Changes

[zac]

The API document can be found on the API page. This thread serves to highlight any changes which occur.

[jazzychad]

Might want to mention that these are GET parameters, though I would argue that they should be sent as POST vars.

[cpeel2300]

Being a bit of a web noob, what's the 40-byte 'api key' and how is this generated?

Thanks

Chris

[Thickey]

Being a bit of a web noob, what's the 40-byte 'api key' and how is this generated?

Chris,

If you log into your prowl account at https://prowl.weks.net/ under settings there is a new API section at the top of the page.

The API interface is much easer for me to get working than the previous way of interaction, I have already changed my PHP script, it only took 5 mins.

[Thickey]

OK so I have some questions now..

When I send a message with PHP I am just usign PHP to hit a url with the correctly formatted variables so

Code: Select all

https://prowl.weks.net/publicapi/add?apikey=xxxx&application=test 1&event=test event&description=something happened&priority=1

My issue is with line breaks and £ sign in the event/description text. I replace the spaces with %20 the HTML equivalent which works ok, but \n seems to show as - (i have tired replacing with <br> but surprise that did not work )
Also the £ symbol is a pain in the arse, the HTML equivalent &pound; does not work and a raw ascii £ makes even more problems. I have had to resort to not using a symbol at all.

Anyone have any ideas?

My PHP Code is below..

Code: Select all

<?
      $api_key = "xxxx";
      $app_name = "App Name";
      $event = "An Event";
      $description = "I am a description\nnew line1\nline2";
      $priority = 0;
            
      $url = "https://prowl.weks.net/publicapi/add?apikey=".$api_key."&application=".$app_name."&event=".$event."&description=".$description."&priority=".$priority;
      
      //replace spaces      
      $url = str_replace(" ","%20",$url);
      
      //remove £
      $url = str_replace("£","",$url);

      //replace line breaks with 2 spaces
      $url = str_replace("\n","%20%20",$url);

      $handle = fopen($url, "rb");
      $contents = stream_get_contents($handle);
      fclose($handle);
?>


[fheusel]

Anyone have any ideas?

Use urlencode() on $app_name, $event and $description.

[tomtaylor]

This looks great, but like jazzychad, I'd argue that this should use the POST method. The last thing you want is for someone to leave their URL somewhere on the web by accident and for it to get crawled, or accidentally clicked on.

Also, an OAuth API would be great. This could mean that I could hand out access to my Prowl account to 3rd party providers, and revoke it at any time without affecting the other providers I use.

[cpeel2300]

Being a bit of a web noob, what's the 40-byte 'api key' and how is this generated?

Chris,

If you log into your prowl account at https://prowl.weks.net/ under settings there is a new API section at the top of the page.

The API interface is much easer for me to get working than the previous way of interaction, I have already changed my PHP script, it only took 5 mins.

Thanks, I should have checked that. Sorry...

The URL you posted WRT your £ symbol issues helped as well (I'm going to hit that too as I'm UK-based).

[pixeltrix]

My suggestions would be to make the API more RESTful - http://en.wikipedia.org/wiki/Representa ... e_Transfer and add JSON output as well as XML.

e.g: Create a new notification

https://prowl.weks.net/api/notifications.format (POST)

and

https://prowl.weks.net/api/keys/{key}/verify.format (GET)

where format is either xml or json.

[jacobb]

A snippy roy fielding would argue that's more REST-like than RESTful, but that's getting overly nitty, and a real RESTful API is probably not very useful in this case. Switching to post to be closer to REST couldn't hurt, though

I wouldn't mind seeing JSON as an available format too, but given that (right now) not a lot of data is actually required back [other than errors], not a huge concern of mine.

[pixeltrix]

A snippy roy fielding would argue that's more REST-like than RESTful, but that's getting overly nitty, and a real RESTful API is probably not very useful in this case. Switching to post to be closer to REST couldn't hurt, though

True, but if the response included a notification id the API could be extended to support viewing, updating and deleting notifications which could be used by AJAX clients to provide a feed of Growl or other notifications on a website, hence the suggestion for JSON output as well.

[zac]

JSON wouldn't be too difficult. I'll look into allowing POST for these options as well, that shouldn't be too hard.

[silverone]

Hey guys,

I've tried to implement your API in PHP using cURL, but I'm experiencing some problems.
So first of all the source:

Code: Select all

<?php

class Prowl {
   private $apikey;
   private $application;
   
   function Prowl($apikey, $application) {
      $this->apikey = $apikey;
      $this->application = $application;
   }
   
   function add($priority, $event, $description) {
      $url = 'https://prowl.weks.net/publicapi/add?apikey=' . urlencode($this->apikey) .
         '&priority=' . urlencode($priority) .
         '&application=' . urlencode($this->application) .
         '&event=' . urlencode($event) .
         '&description=' . urlencode($description);
      
      echo $url; // for debug purposes only

      $ch = curl_init($url);
      $output = curl_exec($ch);
      curl_close($ch);
   }
}

$test = new Prowl("%valid_key%", "Some App");
$test->add(0, "Foo", "Bar");

?>


URL generation works quiet well, executing the URL manually pushes a nice messenge to my phone. But the Call procedure isn't working at all. I also tried some curl_opts like

Code: Select all

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);


but without any sucess.

I hope someone here is able to help me Thanks in advice.

[Thickey]

Code: Select all

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);


Can I ask from a technical point of view what the advantages of using cURL are over using fopen (see my code above for an example). the fopen negotiates the https with out any problems at all. Am I missing something?

[silverone]

cURL was used by another developer's implementation for Prowl. Reason was the HTTP authorization which was required to gain access to the older Prowl API. I don't think that there is an advantage of using cURL anymore - fopen might be better because cURL isn't aviable on most PHP installations. Unfortunately I couldn't get fopen to work aswell, but i thought maybe php's security configuration was preventing it from calling scripts on remote servers. But actually - i don't know exactly.

Code: Select all

Warning: fopen(https://prowl.weks.net/publicapi/add?apikey=...&priority=0&application=Some+App&event=Foo&description=Bar) [function.fopen]: failed to open stream: No such file or directory in /home/silver/public_html/prowl.php on line 21

I was using the same approach as you in your prior post.

[Thickey]

I was using the same approach as you in your prior post.

OK, I thought I was doing something crazy. With PHP as in most programming languages there are many ways to do the same thing. I would suggest perhaps trying a different url to see if that works etc...

[silverone]

fopen is expecting 'http://' since PHP version 4.3.1. Everything else will tell the script to look locally for the file. So you might have a PHP Version < 4.3.1 so it works for you but not for me

[zac]

I will take a look and see what cURL is needed. I also am going to purchase a correct/validated SSL certificate so you won't need to disable verification.

[jazzychad]

Can I ask from a technical point of view what the advantages of using cURL are over using fopen (see my code above for an example). the fopen negotiates the https with out any problems at all. Am I missing something?

If the API changes to using POST (yes, please) to add messages, then fopen won't work since all it can do is GET. cURL does POST like a champ.

Btw, here are the curl_opts I'm using in my PHP script.

Code: Select all

$url = /* some valid prowl url */
   
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);


[silverone]

So, I solved my problem. cURL wasn't compiled with SSL Support.

I've managed to write some working code, unfortunately there's still no sort of error handling because I'm new to parsing XML. If someone is still interessted in the code, here we go:

Code: Select all

<?php

class Prowl {
   private $apikey;
   private $application;
   
   function Prowl($apikey, $application) {
      $this->apikey = $apikey;
      $this->application = $application;
      $this->verify();
   }
   
   function add($priority, $event, $description) {
      $options = array(
         'apikey' => $this->apikey,
         'priority' => $priority,
         'application' => urlencode($this->application),
         'event' => urlencode($event),
         'description' => urlencode($description)
      );
      $this->request('https://prowl.weks.net/publicapi/add', $options);
   }
   
   function verify() {
      $options = array('apikey' => $this->apikey);
      $this->request('https://prowl.weks.net/publicapi/verify', $options);
   }
   
   private function request($file, $options) {
      $url = $file;
      
      $first = true;
      foreach ($options as $key => $value) {
         $url .= ($first ? '?' : '&') . $key . '=' . $value;
         $first = false;
      }
      
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_HEADER, false);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
      curl_setopt($ch, CURLOPT_TIMEOUT, 10);
      $response = curl_exec($ch);
      curl_close($ch);
   }
}

// Sample code

$test = new Prowl("0123456789abcdef0123456789abcdef01234567", "Some Application");
$test->add(0, "Event", "Description");

?>

Thanks for your help.