search

lpradel / steam-web-api-java

:steam_locomotive: Java library to provide access to the data available from Valve's Steam API
Apache License 2.0
77 stars 16 forks source link
steam steam-api

readme

Steam Web API for Java

build Coverage Status Maven Central

This library provides access to the data available from Valve's Steam API for Java applications. The available systems/interfaces are documented in the Valve Developer Community Wiki.

The resulting data is mapped to POJOs with canonical accessors which can be consumed to evaluate the result data. The only requirement to use this library is a Steam Web API Key. Once provided, it takes 3 lines of Java code to consume a Steam webservice with this library (see Usage below).

Installation

The installation process of this library depends on your build system and dependency management. The necessary steps for the most common approaches are listed below.

Maven

Include the following dependency in your POM:

<dependency>
    <groupId>com.lukaspradel</groupId>
    <artifactId>steam-web-api</artifactId>
    <version>1.9.0</version>
</dependency>

Ant

If your build system is ANT you will need to include the .jar in your classpath. An example could look like this:

[...]

<property name="src.dir" value="src"/>
<property name="lib.dir" value="../jars"/>

<path id="external.jars">
    <fileset dir="${lib.dir}" includes="**/*.jar"/>
</path>

<path id="project.classpath">
    <pathelement location="${src.dir}"/>
    <path refid="external.jars" />
</path>

[...]

Furthermore, you need to ensure that the .jar is present at runtime. This depends on your specific build and will vary for .jar artifacts, web applications and so forth.

Manual

You can download the artifact manually from Sonatype Nexus or Maven Central.

Dependencies

The library itself has the following dependencies:

You will have to ensure their presence if you installed manually or using ANT. Maven will take care of this for you.

Usage

Quick Start

In this section you will find a minimal code example to get started in a few minutes. If you are looking for more detailed information check out the next section.

package com.lukaspradel.steamapi.webapi.demo;

import com.lukaspradel.steamapi.core.exception.SteamApiException;
import com.lukaspradel.steamapi.data.json.appnews.GetNewsForApp;
import com.lukaspradel.steamapi.webapi.client.SteamWebApiClient;
import com.lukaspradel.steamapi.webapi.request.GetNewsForAppRequest;
import com.lukaspradel.steamapi.webapi.request.builders.SteamWebApiRequestFactory;

public class SteamWebApiDemo {

    public static void main(String[] args) throws SteamApiException {

        SteamWebApiClient client = new SteamWebApiClient.SteamWebApiClientBuilder("Your-Web-API-Key").build();
        GetNewsForAppRequest request = SteamWebApiRequestFactory.createGetNewsForAppRequest(570); // appId of Dota 2
        GetNewsForApp getNewsForApp = client.<GetNewsForApp> processRequest(request);
    }

}

The result data is in the GetNewsForApp POJO.

In-depth guide

This library provides POJOs for all responses to the various requests a user might send to the Steam API. These are generated from JSON Schema.

First, determine which interface/request you need from the Valve Developer Community Wiki.

Note that most requests require a Steam Web API Key. To use this library you must first request your key here.

Once you have your key, the first step is to create an instance of SteamWebApiClient:

SteamWebApiClient client = new SteamWebApiClient.SteamWebApiClientBuilder("Your-Web-API-Key").build();

Create an instance of the necessary request. There are two approaches to do this. For this example we are assuming that you want to get news for Dota 2, i.e. create a GetNewsForApp request with appid 570 (Dota 2).

Your first option is to invoke the relevant SteamWebApiRequestFactory for this purpose:

GetNewsForAppRequest request = SteamWebApiRequestFactory.createGetNewsForAppRequest(appId);

Alternatively, you can use the relevant GetNewsForAppRequestBuilder of the request directly. For the purpose of illustration we create a GetNewsForAppRequest with a maximum of 10 news each with a maximum length of 500 here:

GetNewsForAppRequest request = new GetNewsForAppRequestBuilder(570).count(10).maxLength(500).buildRequest();

Finally, invoke the processRequest method of SteamWebApiClient:

GetNewsForApp getNewsForApp = client.<GetNewsForApp> processRequest(request);

The result data is in the GetNewsForApp POJO. You can access it using the accessors of the POJO in question.

FAQ

Q: GetOwnedGames request returns null values for game name, only appId is present in output?

A: Make sure to set the designated request option include_appinfo in your request with the builder method includeAppInfo like so:

  GetOwnedGamesRequest req = new GetOwnedGamesRequest.GetOwnedGamesRequestBuilder( "steamId" ).includeAppInfo(true).buildRequest();

Or use the other factory method

SteamWebApiRequestFactory.createGetOwnedGamesRequest(String steamId, boolean includeAppInfo, boolean includePlayedFreeGames, List<Integer> appIdsFilter)

which accepts includeAppInfo.

See Steam API documentation for GetOwnedGames and this StackOverflow question for detailed answer.

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request :)

Releasing

Use the following Maven settings.xml with valid GPG key / Sonatype user:

<settings>
    <profiles>
        <profile>
            <id>release</id>
            <properties>
                <gpg.keyname>###</gpg.keyname>
                <gpg.passphrase>###</gpg.passphrase>
            </properties>
        </profile>
    </profiles>

    <servers>
        <server>
            <id>sonatype-nexus-snapshots</id>
            <username>###</username>
            <password>###</password>
        </server>
        <server>
            <id>sonatype-nexus-staging</id>
            <username>###</username>
            <password>###</password>
        </server>
    </servers>
</settings>

Release to Sonatype Nexus with the following command:

mvn clean deploy -P release

History

Credits

License

Copyright 2015 Lukas Pradel

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.