2013 Which places API should be used

Socially integrated

In the private as well as in the professional environment of many people, social networks have acquired enormous importance. XING is well in the running in Germany in a professional context with over six million users (13 million worldwide), which is documented by a high number of paying premium users [a].

By integrating the static and dynamic data contained in social networks (user data, contacts, job offers, messages, etc.) and functions (login, sending messages or status updates) into their own applications, developers can open up many new application potentials.

For this reason, at the turn of the year 2012/2013, XING released access for external applications via a publicly available API. They allow developers to use the data and functions of XING in their own applications. The Google App Engine (GAE) and the Google Web Toolkit (GWT) are used below to create a sample application.

Due to the almost one-year beta test phase, which was only available to a limited group of participants, a number of interesting applications have already been developed that use the API. A selection of these is shown in the gallery on the developer page [b]. Examples of applications in the App Gallery, without claiming to be exhaustive, are

- an integration with an applicant management system with which job offers can be posted directly on XING and with which applicants can apply for the offer with their XING data (Promerit XING Connector),

- an integration solution for the widespread cloud-based customer relationship management system Salesforce.com, so that the data from XING is available there (Connect for XING),

- a mobile solution for tracking XING contacts who are currently nearby (Radar for XING),

- the mobile apps from XING, which also use the public API.

API divided into functional areas

XING's API makes the essential data and functions of the platform available for external use. For the sake of clarity, the API is divided into different functional areas (profiles, contacts, messages, etc.) so that the user of the API can easily find their way around (see table “Functional areas of the XING API”).

From a technical point of view, the API is used through proven web technologies. The individual functions are available as RESTful Services (Representational State Transfer), which either return XML data (Extensible Markup Language) or, as standard, the more compact JSON format (JavaScript Object Notation).

Programmers can conveniently test all calls using the API Explorer integrated on the developer side. You can specify the parameters relevant for the respective function and choose whether the output should be in JSON or XML. Figure 2 shows an example of calling up your own profile, in which the fields known from the familiar XING web application are returned. The specific order of the fields can change from call to call.

The authentication and authorization takes place according to the OAuth procedure widespread in the web environment in version 1.0 [c]. OAuth provides a token-based mechanism with which a service provider (in this case XING) can provide a user with secure access to their data via an external application (consumer). It usually makes sense to abstract the OAuth mechanisms using a suitable library (see the sample application).

To test access to the API, ShowMyContacts was developed as an application with which a user can display the (professional) locations of his contacts on a Google map. This function was integrated into XING a few years ago, but the company removed it again. Since many users missed this function, it offered itself as a sample application. It is available on the Google App Engine public page Appspot.com [d].

ShowMyContacts: Geographic contacts

ShowMyContacts is based on Google's App Engine, which has the advantage that Java and Python applications can be made publicly available free of charge (for GAE and other tools see “All Links”). For ShowMyContacts Java was used. In this context, it makes sense to use the Google Web Toolkit (GWT) as a web framework, which makes it possible to develop web applications in pure Java and thus to use the advantages of the language such as type safety and a large number of useful libraries. A cross compiler uses part of the Java code to generate the client-side JavaScript code for different browsers, so that an interactive web application is created. In Java or GWT, there are convenient libraries available for using the Google Maps API, so that the generation and control of the maps can also be done in pure Java, which in turn is implemented by the GWT cross compiler in JavaScript.

Users operate the application in the browser, which uses the GWT-RPC (Remote Procedure Call) mechanism to retrieve data from the ShowMyContacts server. This in turn calls up the data via the API and sends it back to the client asynchronously. The Google services (i.e. the Maps API for displaying the map, the Charts API for the symbols and the geocoding API for the localization of the addresses) are controlled from the JavaScript generated in the client.

For security reasons, it must be ensured that no security-relevant information (especially the API access keys) gets into the generated JavaScript code on the client. Although you can obfuscate the JavaScript code in the GWT, there would otherwise be an easy-to-use security hole.

In order to be able to use XING's API, developers must first obtain the access data for the application to be developed from XING in accordance with the OAuth procedure. These consist of a consumer key, which identifies the application, and a consumer secret, which, as the name suggests, must remain secret. For this you have to provide information about the application (URL, short description, usage guidelines, name and address of the operator). XING differentiates between test and production access data and recommends that you first develop and test the application with the test access data. Programmers can use all functional areas of the API, but they receive strongly alienated data returned.

If the application is largely complete, you can apply for productive access, in which you have to explicitly specify the API functions required in the application, which the end user must also release later when using (analogous to mobile apps). If XING grants productive access, you will be sent two PINs, which in turn enable access to the productive key or the productive secret. The second PIN is sent by post after a manual check so that the stored address is verified at the same time.

Calling individual functions of the API

After successful registration (test or production), developers can call up the individual functions of the XING API. In doing so, they must adhere to the sequence specified by the OAuth protocol. In order to reduce the technical complexity at this point, XING uses the open source library Scribe [e], which encapsulates the OAuth functions in Java and predefined classes for using the XING API and other services such as Facebook, LinkedIn, Google and Twitter offers.

The procedures required to call individual functions of the XING API are shown in an excerpt from the server-side Java code (XINGAccess.java). In a preparatory step, the Scribe service must be configured. Among other things, you have to transfer the API key, the API secret and the callback address of your own site (in this case ShowMyContacts).

In step 1 (this and the following steps can be found in the listing and in Figure 5), the so-called request token is requested from XING on the basis of this data. In the positive case, i.e. if the transferred data is OK, the so-called Authorization URL can be created via Scribe. The base URL for the XING authorization is already stored in the corresponding class in Scribe. In step 2, the user “wanders” to the XING login page for the respective application for authentication, in this case ShowMyContacts. The login step is not necessary if, like many frequent users, you are permanently logged into XING.

If the authentication is successful, the user ends up on the authorization page when using the application for the first time. There he gets information about the application as well as the required authorizations for it. If the user confirms this, it continues. In the XING profile, under “Settings -> Privacy” you can see which applications have been granted access. If necessary, access to these applications can be withdrawn there. With applications in test mode, all rights are always granted, but using falsified data.

After successful authentication or authorization, XING redirects the user to the website specified in the callback URL. Usually this is the one from which the process was started. For security reasons, XING checks that the callback URL matches the URL that was stored when applying for the productive key.

An additional URL parameter Verifier which, together with the request token, serves to retrieve the so-called access token (step 3). Only this token allows access to the technical functions of the API, as this is the only way to ensure that the user is authenticated and that he grants the application the necessary rights. The verifier can also be transferred manually (out-of-band authorization, OOB), which, however, is generally not acceptable for the end user, since in this case he has to manually transfer the verifier to the consumer application.

In step 4, you can use the access token to make a call to the API to access the protected resources. The call returns a result object (Response), which, depending on the configuration, is an XML data structure or a JSON structure. In the example application this is JSON. Step 5 describes how the returned data is to be processed. The open source framework Jackson [f] is used to manage and simplify the processing of JSON data (in Java). A useful page in this context is jsonschema2pojo [g], which helps to generate Java wrapper classes from JSON schemas or complex JSON example objects, which can be filled from the JSON data stream using the Jackson ObjectMapper. You can then conveniently access the individual sub-objects or attributes from Java. The code example outputs the display name of the contact, which also appears on XING.

To display the contacts, the application must read them; however, you can use the access token you have already purchased. Google's Maps API and the geocoding API contained therein are used for representation in the narrower sense. The Maps API is conveniently encapsulated in GWT by modules. Google's Charts API is used to generate the dynamic images required to display the markers.

In order to enable parallel use by several users with different access data, a session management system must be available on the server side, which manages the access data on the basis of the HTTP sessions, as the server only temporarily stores them between the individual calls for security reasons. The login data (name and password) of the individual users are not used at all, but are only entered in the authentication dialog provided by XING.

Limiting Terms of Use

When developing applications that use the XING API, you should study the terms of use carefully, otherwise XING may not activate productive access. On the developer page [b] there are specifications regarding the naming and graphic design of an application: For example, it may not pretend to be XING itself, but must use the XING login buttons.

iX-TRACT

  • The XING business network allows developers to access user data via an interface if the latter allow it.
  • The server transmits either XML or JSON data using REST.
  • For the security of the data, the authentication must run via OAuth 1.0.
  • An example application shows your own contacts on a map.

Furthermore, there are restrictions on the number of API calls per minute, hour and day based on individual end users (users) or on the entire application (consumer). These restrictions (around 120 requests per user per minute) are definitely sufficient for initial test applications.

Since the API is independent of the implementation technology of the consumer application and has been available for some time at least for closed beta developers, in addition to the first finished applications, a number of frameworks and code examples for accessing the API from other environments can be found on the Internet, for example from PHP, Ruby or iOS. The examples on the XING developer page are usually shown in Ruby, as the platform mainly uses this language.

Conclusion

In developing the sample application, it was found that the API is stable and well documented. Although it is still in (further) development, it is encouraging that XING's mobile applications use the interface themselves. Since it can never be completely frozen in a living platform, further changes are to be expected in the future. As a rule, however, XING wants to make these changes downward compatible. The company wants to mark functions that can no longer be used in the future as outdated (deprecated) at an early stage.

An exciting source of information for APIs on the Internet in this context is the ProgrammableWeb [i] page. Furthermore, a number of so-called API management platforms such as Mashery or 3Scale have developed in recent years (see “All links”), which offer companies the infrastructure to publish and manage their APIs. For example, Intel acquired Mashery for a substantial amount in April 2013, which underscores the importance of this topic. (hb)

Oliver Höss

is professor for business informatics and head of the laboratory for business software at the Stuttgart University of Applied Sciences (HFT Stuttgart).

Jürgen Falkner

is head of the software technology competence team at Fraunhofer IAO and spokesman for the Fraunhofer Cloud Computing Alliance.

Mohammed Shohrab Uddin

is a student in the international master's program in Software Technology at the HFT Stuttgart.

Anette Weisbecker

is the director of the institute and head of the information and communication technology division at Fraunhofer IAO.

All links: www.ix.de/ix1307146

Listing: Use of the XING API in Java using the Scribe library

// Server-side Java code // for an overview without frame code, exceptions and error handling // Constants // KEY 20 character private static final string APIKEY = "xxxxxxxxxxxxxxxxxxxx"; // SECRET 40 character private static final string APISECRET = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"; // URL of the XING function to be called private static final String PROTECTED_RESOURCE_URL = "https://api.xing.com/v1/users/me"; // Callback URL (checked by XING) private static final String CALLBACK = "http://showmycontacts.appspot.com/"; // Configuration of the Scribe-OAuth-Service-Object (Method Chaining) OAuthService service = new ServiceBuilder (). Provider (XingApi.class) .apiKey (APIKEY) .apiSecret (APISECRET) .callback (CALLBACK) .build (); / / Step 1: Request token; Token requestToken = service.getRequestToken (); // Construct the authorization URL String authURL = service.getAuthorizationUrl (requestToken); // Step 2: Forward user in the client to the XING authorization page // Takes place on the client Page and is not shown here // In GWT simply with Window.Location.assign (authURL); // Step 3: After authorization // Extract the verifier from the URL on the client side (string v) and request the access token // Extraction takes place on the client Page and is not shown here Verifier verifier = new Verifier (v); Token accessToken = service.getAccessToken (requestToken, verifier); // Step 4: Query the protected resources // Here: own ProfilOAuthRequest request = new OAuthRequest (Verb.GET , PROTECTED_RESOURCE_URL ); service.signRequest (accessToken, request); Response response = request.send (); // Step 5: Processing the information // Processing the complex JSON object through generated Jackson objects ObjectMapper mapper = new ObjectMapper (); jackson. Users users = mapper.readValue (response.getBody (), jackson.Users.class); // Output display name for test (title, first name, last name) System.out.println (users.getUsers (). Get (0). getDisplay_name ());