Getting started with the server-side SPiD API

When you have completed this guide, you will have connected your application to the SPiD API and made your first call, verifying that your client ID and secrets are correctly configured. You will then be ready to implement login with SPiD.

Downloading the appropriate SDK/Client

To work with the SPiD APIs, it is recommended that you use one of the official SDKs. The SDKs are thin wrappers that primarily spare you the details of working with OAuth. If an SDK is not available for your language, skip this section and refer to the cURL examples below.

NB! Your client secret is highly sensitive. Do not hard-code it, and be careful who you share it with. The examples below are meant to illustrate the basics of using the API, they are not examples of production code. For more complete examples, see the example use-cases.

Java

The Java API client library is deployed in Maven central, just add it to your project's pom.xml file:

<dependency>
    <groupId>no.spid</groupId>
    <artifactId>no.spid.api.client</artifactId>
    <version>1.4</version>
</dependency>

PHP

Download the PHP SDK by cloning the GitHub repository:

git clone https://github.com/schibsted/sdk-php.git

If you do not have Git installed, you can also download a zip file.

Clojure

The Clojure client is deployed in Clojars, just put it in your project.clj:

[spid-client-clojure "1.2.0"]

iOS

Download the iOS SDK by cloning the GitHub repository:

git clone https://github.com/schibsted/sdk-ios.git

If you do not have Git installed, you can also download it as a zip file.

Linking the SDK into your project requires a few steps:

  • Find the .xcodeproj view. At the bottom of the General view, under Linked frameworks and Libraries, click + and Add other. Locate the SDK you downloaded, and add it.

  • Also link in AdSupport.framework as an Optional link. It is only used during build.

  • Go to Build Settings, search for linking and add -ObjC to Other Linker Flags

Android

In order to use the Android SPiD SDK, you must fist install the Android SDK. Run the Android SDK Manager (./sdk/tools/android sdk) and make sure you have installed at least SDK versions 2.2, 4.0, 4.1 and 4.2.

To run the examples, you will also need Maven 3.1.1 or newer. As per the maven-android-plugin getting started, set environment variable ANDROID_HOME to the path of your installed Android SDK and add $ANDROID_HOME/tools as well as $ANDROID_HOME/platform-tools to your $PATH. (or on Windows %ANDROID_HOME%\tools and %ANDROID_HOME%\platform-tools).

Because the Android libraries are not available from any central Maven repository, you also need to use the Maven Android SDK Deployer in order to install the Android libraries to your ~/.m2 directory in order to build the SPiD Android SDK.

git clone https://github.com/mosabua/maven-android-sdk-deployer.git
cd maven-android-sdk-deployer
mvn install -P 2.2,4.0,4.1,4.2

Download the Android SDK by cloning it from GitHub:

git clone git@github.com:schibsted/sdk-android.git

Start by installing the root project, which will build and install the SDK, enabling you to run the provided examples.

cd sdk-android
mvn install

To verify your install, run the AVD - Android Virtual Device Manager. This presumes you updated your $PATH as described above.

android avd

If you haven't already, create a new virtual device by clicking "New". Give it a name, and choose a device, like Nexus 4. Finally, choose "Google APIs - API Level 17" as "Target" and click "Ok".

Select the device from the list and click "Start" to launch it. This will take a while. Maybe 10-15 minutes. Or it might just hang there for an unreasonable long time. We've had luck with deleting the device and starting over.

When the emulator is running, run the SPiD example app:

cd SPiDExampleApp
mvn android:deploy

This will install the app on the emulator. When it finishes you have successfully set up the SDK for development. Great success!

Interacting with the API

Now that you have installed a SDK/Client, you will use it to make first contact with the SPiD API. Don't worry, it will be quick and painless. When you've got everything set up, you might want to continue with configuring single sign-on.

Java

The following is a minimal example of using the Java API client. It fetches the /endpoints endpoint, which returns a description of all available endpoints.

import no.spid.api.client.SpidApiClient;
import no.spid.api.exceptions.SpidApiException;
import no.spid.api.exceptions.SpidOAuthException;
import no.spid.api.oauth.SpidOAuthToken;

import org.apache.commons.codec.binary.Base64;

public class GettingStarted {

    public static void main(String[] args) {
        if(args.length < 3) {
            System.out.println("Run with arguments <clientId> <clientSecret> <email>");
            System.exit(0);
        }
        final String clientId = args[0];
        final String secret = args[1];
        final String signatureSecret = "";
        final String redirectUrl = "http://localhost:8080";
        final String spidBaseUrl = "https://identity-pre.schibsted.com";

        SpidApiClient client = new SpidApiClient.ClientBuilder(
                clientId,
                secret,
                signatureSecret,
                redirectUrl,
                spidBaseUrl
        ).build();

        try {
         SpidOAuthToken token = client.getServerToken();
            final String email = args[2];   // check to see if this email exists
            String base64EncodedEmail = new String(Base64.encodeBase64(email.getBytes()));
            String responseJSON = client.GET(token, "/email/" + base64EncodedEmail + "/status", null).getRawData();
            System.out.println("Status of " + email + ": " + responseJSON);
        } catch (SpidOAuthException e) {
            e.printStackTrace();
        } catch (SpidApiException e) {
            e.printStackTrace();
        }
    }
}

You can run this code from the example repository, filling in your actual client-id and secret:

mvn install -q exec:java -Dexec.mainClass="no.spid.examples.GettingStarted" -Dexec.args="<client-id> <secret>" -e

This returns about 40K of compressed, highly unreadable JSON data. If you have Python installed (most *nixes have, including OSX), you can improve the output by piping to python while including the json.tool library:

mvn install -q exec:java -Dexec.mainClass="no.spid.examples.GettingStarted" -Dexec.args="<client-id> <secret>" -e | python -m json.tool

When working with the Java client, you might be more interested in SpidApiResponse's getJSONData() method.

PHP

The following is a minimal example of using the PHP SDK. It fetches the /endpoints endpoint, which returns a description of all available endpoints.

<?php // getting-started.php
require_once('../vendor/autoload.php');

$client = new VGS_Client(array(
    VGS_Client::CLIENT_ID          => $argv[1],
    VGS_Client::CLIENT_SECRET      => $argv[2],
    VGS_Client::CLIENT_SIGN_SECRET => $argv[3],
    VGS_Client::STAGING_DOMAIN     => "identity-pre.schibsted.com",
    VGS_Client::HTTPS              => true,
    VGS_Client::REDIRECT_URI       => "http://localhost:8181/",
    VGS_Client::DOMAIN             => "localhost:8181",
    VGS_Client::COOKIE             => true,
    VGS_Client::API_VERSION        => 2,
    VGS_Client::PRODUCTION         => false
));

$client->auth();
echo var_dump($client->api("/endpoints"));

You can run this code from the example repository, filling in your actual client-id, secret and signing secret:

php getting-started.php client-id secret sign-secret

This will print the JSON-decoded response from the server, which shows all available endpoints along with details on how to interact with them.

Clojure

The following is a minimal example of using the Clojure client. It fetches the /endpoints endpoint, which returns a description of all available endpoints.

(ns getting-started.core
  (:require [spid-client-clojure.core :as spid]))

(defn test-run-api [client-id secret]
  (let [options {:spid-base-url "identity-pre.schibsted.com"}
        client (spid/create-client client-id secret options)
        token (spid/create-server-token client)]
    (clojure.pprint/pprint (spid/GET client token "/endpoints"))))

You can run this code from the example repository, filling in your actual client-id and secret:

lein run client-id secret

This will pretty-print the JSON-decoded response from the server, which shows all available endpoints along with details on how to interact with them.

iOS

The following is a minimal example of using the iOS SDK. It fetches the /endpoints endpoint, which returns a description of all available endpoints.

Open your *AppDelegate.m file. In the example, this is MyAppDelegate.

We set up the SPiDClient singleton, then we need to fetch a client token to make the /endpoints API call.

#import "MyAppDelegate.h"
#import "SPiDClient.h"
#import "SPiDResponse.h"
#import "SPiDTokenRequest.h"

static NSString *const ClientID = @"your-client-id";
static NSString *const ClientSecret = @"your-client-secret";
static NSString *const AppURLScheme = @"https";
static NSString *const ServerURL = @"https://identity-pre.schibsted.com";

@implementation MyAppDelegate

- (void)getClientToken:(void (^)(SPiDError *response))completionHandler
{
    SPiDRequest *clientTokenRequest = [SPiDTokenRequest clientTokenRequestWithCompletionHandler:completionHandler];
    [clientTokenRequest startRequest];
}

- (void)getEndpoints:(void (^)(SPiDResponse *response))completionHandler
{
    NSString *path = [NSString stringWithFormat:@"/endpoints"];
    SPiDRequest *request = [SPiDRequest apiGetRequestWithPath:path completionHandler:completionHandler];
    [request startRequestWithAccessToken];
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [SPiDClient setClientID:ClientID
               clientSecret:ClientSecret
               appURLScheme:AppURLScheme
                  serverURL:[NSURL URLWithString:ServerURL]];

    [self getClientToken:^(SPiDError *error) {
        if (error) {
            NSLog(@"Error: %@", error);
        } else {
            [self getEndpoints:^(SPiDResponse *response) {
                NSLog(@"Endpoints: %@", [response message]);
            }];
        }
    }];

    return YES;
}

@end

Android

To use the SPiD Android SDK you must first make the library available to your application. Add the SPiD SDK as a dependency to your pom.xml:

<dependency>
    <groupId>com.schibsted.android</groupId>
    <artifactId>spid</artifactId>
    <version>1.1.3</version>
</dependency>

The SPiDClient class is a singleton, and you should configure it in the onCreate handler in your main activity:

@Override
public void onCreate(Bundle savedInstanceState) {
    // ...

    SPiDClient.getInstance().configure(new SPiDConfigurationBuilder()
            .clientID("your-client-id")
            .clientSecret("your-client-secret")
            .appURLScheme("spid-example")
            .serverURL("https://identity-pre.schibsted.com")
            .context(this)
            .debugMode(true)
            .build());

    // ...
}

The app URL scheme is not important for now, and is explained in detail in the Single Sign-On implementation guide.

In order to access the endpoints that don't require a logged in user, you must set the client up with an OAuth access token:

SPiDTokenRequest request = new SPiDTokenRequest(new SPiDAuthorizationListener() {
    public void onComplete() {
        String token = SPiDClient.getInstance().getAccessToken().getAccessToken();
        System.out.println("OAuth token: " + token);
    }

    public void onSPiDException(SPiDException exception) {}
    public void onIOException(IOException exception) {}
    public void onException(Exception exception) {}
});

request.addBodyParameter("grant_type", "client_credentials");
request.addBodyParameter("client_id", SPiDClient.getInstance().getConfig().getClientID());
request.addBodyParameter("client_secret", SPiDClient.getInstance().getConfig().getClientSecret());
request.addBodyParameter("redirect_uri", "http://localhost");

request.execute();

The redirect URL doesn't have any effect in this scenario, but it is required input to the API. Once the request completes successfully, the SPiDClient singleton will have been configured to use it. You can now request the /endpoints endpoint, which describes all available endpoints in the API.

SPiDApiGetRequest request = new SPiDApiGetRequest("/endpoints", new SPiDRequestListener() {
    public void onComplete(SPiDResponse result) {
        // Print 40k of unformatted JSON to Android Logcat
        System.out.println(result.getBody());
    }

    public void onSPiDException(SPiDException exception) {}
    public void onIOException(IOException exception) {}
    public void onException(Exception exception) {}
});

request.addQueryParameter("oauth_token", SPiDClient.getInstance().getAccessToken().getAccessToken());

request.execute();

In practice, it is likely that you will start by logging in the user and then interacting with the API on their behalf. You will learn how to do this from the Single Sign-On guide.

cURL

Using cURL to interact with the API is a good way to gain insight into how it works at the networking level. It is also the most direct way to ensure your credentials are correct as there are fewer layers of abstraction that might fail/be used wrongly.

Start by requesting an OAuth token:

curl -X POST -d "client_id=$client_id&client_secret=$secret&grant_type=client_credentials" https://identity-pre.schibsted.com/oauth/token

If all goes well, you should get a response like this back:

{ "access_token": "68d602d1a3d3cc1b2805cdeb53fb5207d273a7ec",
  "expires_in": 604800,
  "scope": null,
  "user_id": false,
  "is_admin": false,
  "refresh_token": "95ab17a1f78339b7a01b88c748677ed522474e16",
  "server_time": 1392194793 }

Using the provided access_token, you may now browse the API endpoints:

curl https://identity-pre.schibsted.com/api/2/endpoints\?oauth_token=$access_token | python -m json.tool

The pipe into python makes the JSON document nice and readable. You can of course skip that part if you don't have python installed.

Table of Contents

Prerequisites

In order to complete this guide, you need to know your:

  • client ID
  • client secret

If you do not, please set up your API client via our self service tool

See also

Help us improve

Did you spot an error? Or maybe you just have a suggestion for how we can improve? Leave a comment, or better yet, send us a pull request on GitHub to fix it (in-browser editing, only takes a moment).

History of this page

Comments/feedback

Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. SPiD reads and responds to every question. Additionally, your experience can help others using SPiD, and it can help us continuously improve our documentation.