[[TracNav(TracNav)]]
[[TOC]]
Ce document est aussi disponible en [wiki:Fr/AtomApiTutorial/Post Français]

----

== POST ==

You add a new mark on blogmarks.net by posting an Atom entry on a postURI. The postURI is http://api.blogmarks.net/marks.

In the Atom entry, you must specify at least a related link and a title.

=== First example ===

We'll se how to create the most simple allowed blogmark.

Authentication is explained in AtomApiTutorial/Get

The client send

{{{
POST /marks HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Content-Type: text/xml; charset=utf-8
Content-length: 267
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
<title>Znarf Blog</title>
<link rel="related" href="http://upian.net/znarf/blog/" />
</entry>
}}}

The server response :

{{{
HTTP/1.1 201 Created
Date: Wed, 09 Mar 2005 11:21:03 GMT
Content-length: 811
Connection: close
Content-Type: application/atom+xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<entry
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#>
 <id>tag:blogmarks.net,2005:marks,31523</id>
 <title type="TEXT">Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" type="text/html"/>
 <link rel="alternate" href="http://blogmarks.net/user/znarf/archives/2005/03/#mark31523" type="application/xhtml+xml" title="Znarf Blog Test"/>
 <link rel="image" href="http://blogmarks.net/screenshots/2005/03/09/dbc0c60c8794c0ca4f2e99f10a5f2408.png" type="image/png"/>
 <updated>2005-03-09T12:21:03Z</updated>
 <author><name>znarf</name></author>
 <edit>http://api.blogmarks.net/marks/31523</edit>
 <bm:created>2005-03-09T12:21:03Z</bm:created>
</entry>
}}}

=== Second example ===

We'll create a more advanced blogmark.

 * In the Atom mapping, tags are called category
 * By specifing published=0000-00-00, we say that the blogmarks is private (not published)
 * bm:created is the main blogmark date. This is the one which is used to sort blogmarks chronologically

{{{
POST /marks HTTP/1.0
Host: api.blogmarks.net
Accept: application/atom+xml
Content-Type: text/xml; charset=utf-8
Content-length: 535
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="$Username", PasswordDigest="$PasswordDigest", Nonce="$Nonce", Created="$CreationTimestamp"

<?xml version="1.0" encoding="UTF-8"?>
<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
 <title>Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" />
 <link rel="via" href="http://blogmarks.net/" />
 <summary>This blog really rox</summary>
 <category term="http://api.blogmarks.net/tags/" sheme="blog" />
 <category term="http://api.blogmarks.net/tags/" sheme="dotclear" />
 <published>0000-00-00</published>
 <bm:created>2005-03-09</bm:created>
</entry>
}}}

=== Same code in PHP / Pear HTTP Request ===

{{{
<?php

$Username = 'znarf';
$Password = '';
$Nonce = rand( 1 , 100000000000000 );
$CreationTimestamp = date('Y-m-d\Th:i:s\Z');

$PasswordHash = md5( $Password );

$PasswordDigest = base64_encode( sha1( $Nonce . $CreationTimestamp . $PasswordHash  ) );

require_once "HTTP/Request.php";

$req =& new HTTP_Request('http://api.blogmarks.net/marks');
$req->setMethod(HTTP_REQUEST_METHOD_POST);
$req->addHeader('X-WSSE', 'UsernameToken Username="' . $Username . '", PasswordDigest="' . $PasswordDigest . '", Nonce="' . $Nonce . '", Created="' . $CreationTimestamp . '"');

$xml  =
'<?xml version="1.0" encoding="UTF-8"?>
<entry
  version="draft-ietf-atompub-format-05:do not deploy"
  xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05"
  xmlns:bm="http://api.blogmarks.net/ns#">
 <title>Znarf Blog</title>
 <link rel="related" href="http://upian.net/znarf/blog/" />
 <link rel="via" href="http://blogmarks.net/" />
 <summary>This blog rox</summary>
 <category term="http://api.blogmarks.net/tags/" sheme="blog" />
 <category term="http://api.blogmarks.net/tags/" sheme="dotclear" />
 <published>0000-00-00</published>
 <bm:created>2005-03-09</bm:created>
</entry>';

$req->addRawPostData($xml);

$response = $req->sendRequest();

if (PEAR::isError($response)) {
    echo $response->getMessage();
} else {
    $code = $req->getResponseCode();
    switch ($code) {
    case 201:
      echo "OK\n";
      echo $req->getResponseBody();
      break;
    default:
      echo $code . " Error\n";
      break;
    }
}

?>
}}}

=== Good practices ===

 * '''Don't flood''' : Flooding is posting a lot of blogmarks (say more than 5) and by the way filling the Last Public Marks list. Others users really don't like that. The recommended practice is to specify a bm:created in the past. You may have one if you import marks for example. If you don't have one, we recommand to put the current date without specifying the hour. <bm:created>2005-03-08Z</bm:created>


----
See also : [wiki:AtomApiTutorial/Get AtomApiTutorial/Get], [wiki:AtomApiTutorial/Put AtomApiTutorial/Put], [wiki:AtomApiTutorial/Delete AtomApiTutorial/Delete]