Deprecating the REST API

We announced the Graph API at f8 2010. Since that event, we have been working hard to ensure that the most important functionality that developers were using with the REST API is available via the Graph API. For the past several months we have been slowly launching new features in the Graph API to bring it up to parity with the REST API.

Today, we are launching the last two remaining APIs that we intend to port to the Graph API. With this we are officially deprecating the REST API.

Note: Deprecating the REST API does not mean we are removing it, but we are actively encouraging all developers to use the Graph API for any new apps and to move existing apps to use it, as well. Moving forward, all new features will only be available in the Graph API and the level of support will be higher on a non-deprecated API.

Accessing app properties via the Graph API and FQL

We have added the ability to read and manage several new app property fields via the Graph API application object. It is also possible to read these properties via the application FQL table.

To retrieve a list of properties from an app, issue an HTTP GET with an app access_token to https://graph.facebook.com/APP_ID?fields=PROPERTY_NAMES, specifying the names of the property values you want to retrieve in a comma-separated list. See the Graph API application object for a list of available properties and return types.

For example, the following HTTP request retrieves some of the fields related to the new authentication dialog:

 GET https://graph.facebook.com/APP_ID/
     ?fields=auth_dialog_headline,auth_dialog_perms_explanation
     &access_token=APP_ACCESS_TOKEN

To set any properties for an app, issue an HTTP POST with an app access_token to https://graph.facebook.com/APP_ID?PROPERTY=VALUE using the properties and types as defined in the Graph API application object. Not all app properties can be edited via the API, such as id, logo_url, etc. Array properties can be unset by passing an empty array.

For example, the following HTTP request sets some of the fields related to the new authentication dialog:

 POST https://graph.facebook.com/APP_ID/
      ?auth_dialog_headline=My%20great%20headline
      &auth_dialog_perms_explanation=Some%20explanatory%20text
      &access_token=APP_ACCESS_TOKEN

You can obtain an app access_token from the Graph API token endpoint at https://graph.facebook.com/oauth/access_token. See the App Login section of the Authentication documentation for more information.

Accessing Developer Roles for an App via the Graph API and FQL

We have added the ability to read and manage developer roles for an application via the roles connection on the Graph API application object. It is also possible to query developer roles via the developer FQL table.

In order to read the developer roles for an app, issue an HTTP GET request to https://graph.facebook.com/APP_ID/roles using an app access_token. We will return an array of objects containing string properties app_id, user and role. The possible values for role are administrators, developers, testers or insights users.

To add a developer role, a user access_token for a user who is an administrator of the app is required. Issue an HTTP POST request to https://graph.facebook.com/APP_ID/roles, with the user_id specified in the user field, and the role (as above) in the role field. This returns true if successful. The user being added will receive a request via the Developer app which they will need to accept before the role is confirmed.

To remove a developer role, a user access_token for a user who is an administrator of the app is required. Issue an HTTP DELETE request to https://graph.facebook.com/APP_ID/roles, with the user_id specified in the user field. This will return true if successful, and the user will be removed immediately.

Here is some sample code which reads all developer roles for your application using an app access token, and will allow a logged in app administrator to add and remove roles via calls to FB.api() using the JavaScript SDK.

<?php
$app_id = 'YOUR_APP_ID';
$app_secret = 'YOUR_APP_SECRET';

// Query app access token
$app_access_token = file_get_contents(
  'https://graph.facebook.com/oauth/access_token?' .
  'client_id='.$app_id.'&client_secret='.$app_secret.'&' .
  'grant_type=client_credentials');

// Query app developer roles
$roles = json_decode(file_get_contents(
  'https://graph.facebook.com/'.$app_id.'/roles?' .
  $app_access_token
));

?>
<html>
  <body>
    <div class="fb-login-button">Login with Facebook</div>

    <h3>Existing Roles</h3>
    <p>
      <?php foreach ($roles->data as $role) { ?>
        user: <?php echo $role->user ?> / 
        role: <?php echo $role->role ?> - 
        <a href="javascript:removeRole(<?php echo $role->user ?>)">remove</a><br />
      <?php } ?>
    </p>

    <h3>Add new role</h3>
    <p>
      user: <input type="text" id="user" /> / 
      role: <input type="text" id="role" /> - 
      <a href="javascript:addRole()">add</a>
    </p>

    <p>Check developer console for API response.</p>

    <div id="fb-root"></div>
    <script src="http://connect.facebook.net/en_US/all.js"></script>
    <script>
    // Define APP_ID
    var APP_ID = <?php echo $app_id ?>;

    FB.init({
      appId  : APP_ID,
      status : true, // check login status
      cookie : true, // enable cookies
      xfbml  : true, // parse XFBML
      oauth  : true // enable OAuth 2.0
    });

    // Function to remove role for a given user
    var removeRole = function(user) {
      FB.api('/' + APP_ID + '/roles', 'delete', { user: user }, logResponse);
    };

    // Function to add new role for a given user
    var addRole = function() {
      user = document.getElementById('user').value;
      role = document.getElementById('role').value;
      FB.api('/' + APP_ID + '/roles', 'post', 
           { user: user, role: role }, logResponse);
    };

    var logResponse = function(response) {
      console.log(response);
    };
   </script>
  </body>
</html>

Please provide thoughts and feedback in the comments below.