Performing actions with objects in REST (subscribe / mark as read / etc.) - rest

Question

I am reading over Creating an efficient REST API and I understand and agree with a lot of what the document has to say.
I'm currently implementing a Twitter clone and each tweet object in the database has a list of readers (user IDs).
According to the document, it seems like the request for this would be something like:
PATCH /tweet
{read: true}
However read is not an actual property of the tweet. Instead this would actually update the list of readers on the tweet with the currently authenticated user. Is this correct?
This also means that the user could potentially perform other operations on the tweet using this same API route, but users cannot actually update/PATCH tweets in any way other than to mark them as read or not.
Additionally, only an authenticated user should be able to do this and it should only update the list of readers for them. The document says that you should not handle state in your API which means no sessions -- however authentication is obviously necessary. It seems to say that you should send the authentication/authorization token each time, but I don't understand how this is substantially different from a session cookie in some cases. Is the implication that the request should actually be:
PATCH /tweet
<Authentication-Header>
{userId: userId, read: true}
i.e. should the API itself not try to use information from the session and force requests to provide logged-in user information? Is there a better way to structure this?

Answer 1

Depends on what level of authentication is necessary.
Keep it simple. No need to complicate things.
Do you really need a "state"? You have a database where you have to check the user authentication. Why not use the database record?
If the API will be used by the client on their web server, then you just have to check the IP address of the request.
The IP address cannot be spoofed and therefore is a very good authentication factor. Add username and you have multi-factor authentication
Instruction for client using PHP
$user = 'joe';
$param = 1;
file_get_contents("http://apisite.com/api/function/?id=$user&param=$param");
An HTML form, maybe you'd have to restrict access but if they name name the page something not easy to guess, then you have it.:
<form action="http://apisite.com/api/function/">
<input type="textarea" name="tweet"/>
<input type="hidden" name="user" value="joe" />
<input type="hidden" name="param" value="1" />
</form>
If the API were to be done in PHP:
PHP
<?php
header('Content-Type: text/plain; charset=utf-8');
header('Cache-Control: max-age=0');
$ip = $_SERVER['REMOTE_ADDR'];
$results = mysqli_query("SELECT COUNT(*),`user`,`state` FROM `Profile` WHERE `ip` LIKE '$ip' ");
$row = mysql_fetch_array($results, MYSQL_NUM);
if ($row[0] == 1 && $row[1]==$_GET['user']) && $row[2]==1){
$tweet = trim($_GET['tweet']);
$param = $_GET['param'];
include('tweet.php');
echo "Sent\n";
}
else{
echo "Not Sent\n";
}
?>

Answer 2

The problem with using cookies is that you are moving state outside of the URI and into the cookie.
RESTful APIs should have all the state necessary in the URI. Believe it or not but this does make things a lot easier as you don't have to mess around with handling cookies if you are creating a new client library.
Not using cookies also makes for really nice integration with other devices. Say I am viewing a RESTful webpage on my browser, and then I want to show someone something on my account. I can email them the URI /some-uri?authToken=1234 and they will be able to view my account without me giving them my password!!
Once the token expires, they will no longer be able to access the account.
EDIT
If you put the token in the POST body, a user won't be able to visit a page by typing in the address bar. They will keep being told they are not authorised. So yes, you need it in the URI. You can use a cookie if you really want, but except that it is a workaround.
You'd get the login token by exposing a login resource. To login you would send your username and password to:
POST /login
This would create a /login/{token} resource. You can use this token (or even the full URI if you want) to authenticate with the server.
When you want to log out, you call
`DELETE /login/{token}`
If you try to use the token now, the API should return with 'not authenticated' as the token no longer exists.