Java SDK

The ButterCMS Java SDK provides type-safe, strongly-typed response objects for Spring Boot, Quarkus, and vanilla Java applications.

Installation

Maven

Add to your pom.xml:

<dependency>
  <groupId>com.buttercms</groupId>
  <artifactId>buttercmsclient</artifactId>
  <version>1.13.0</version>
</dependency>

Gradle

Add to your build.gradle:

dependencies {
    implementation 'com.buttercms:buttercmsclient:1.13.0'
}

Initialization

Initialize the SDK with your Read API token from the ButterCMS Settings.

import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;

// Basic initialization
IButterCMSClient client = new ButterCMSClient("your_api_token");

// With preview mode enabled
boolean isPreviewEnabled = true;
IButterCMSClient client = new ButterCMSClient("your_api_token", isPreviewEnabled);

Configuration options

The client constructor accepts additional parameters for customization:

// With custom timeout (in milliseconds)
IButterCMSClient client = new ButterCMSClient(
    "your_api_token",
    false,  // preview mode
    10000   // timeout in ms
);

// With custom HttpClient
HttpClient customClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .build();

IButterCMSClient client = new ButterCMSClient(
    "your_api_token",
    customClient,
    false  // preview mode
);

API methods

All methods return strongly-typed response objects.

Pages

Retrieve and search pages created in the ButterCMS dashboard.

import com.buttercms.model.Page;
import com.buttercms.model.PagesResponse;
import java.util.HashMap;
import java.util.Map;

// Build query parameters
Map<String, String> params = new HashMap<>();
params.put("locale", "en");
params.put("preview", "1");
params.put("levels", "2");

// Fetch a single page
Page page = client.getPage("landing_page", "home-page", params);
System.out.println(page.getFields().get("headline"));

// Fetch paginated pages
params.put("page", "1");
params.put("page_size", "10");
PagesResponse<Page> pages = client.getPages("landing_page", params);

for (Page p : pages.getData()) {
    System.out.println(p.getSlug());
}

// Access pagination metadata
System.out.println("Next page: " + pages.getMeta().getNextPage());

Collections

Fetch content from Collections (structured data tables).

import com.buttercms.model.CollectionResponse;
import java.util.Arrays;
import java.util.Map;

Map<String, String> params = new HashMap<>();
params.put("locale", "en");

// Fetch collection content
CollectionResponse response = client.getCollection(
    Arrays.asList("faq", "navigation"),
    params
);

// Access collection data
List<Map<String, Object>> faqItems = response.getData().get("faq");
for (Map<String, Object> item : faqItems) {
    System.out.println(item.get("question"));
    System.out.println(item.get("answer"));
}

Blog Posts

Access the built-in Blog Engine for posts, categories, tags, and authors.

import com.buttercms.model.Post;
import com.buttercms.model.PostsResponse;
import com.buttercms.model.PostResponse;

// Build query parameters
Map<String, String> params = new HashMap<>();
params.put("page", "1");
params.put("page_size", "10");
params.put("exclude_body", "true");

// List blog posts
PostsResponse postsResponse = client.getPosts(params);

for (Post post : postsResponse.getData()) {
    System.out.println(post.getTitle());
    System.out.println(post.getSlug());
}

// Access pagination
System.out.println("Total: " + postsResponse.getMeta().getCount());
System.out.println("Next page: " + postsResponse.getMeta().getNextPage());

// Fetch a single post
PostResponse postResponse = client.getPost("my-post-slug");
Post post = postResponse.getData();
System.out.println(post.getTitle());
System.out.println(post.getBody());

// Search posts
params.put("query", "search term");
PostsResponse searchResults = client.getSearchPosts(params);

Authors

import com.buttercms.model.Author;
import com.buttercms.model.AuthorsResponse;
import com.buttercms.model.AuthorResponse;

Map<String, String> params = new HashMap<>();
params.put("include", "recent_posts");

// List all authors
AuthorsResponse authorsResponse = client.getAuthors(params);

for (Author author : authorsResponse.getData()) {
    System.out.println(author.getFirstName() + " " + author.getLastName());
}

// Fetch a single author
AuthorResponse authorResponse = client.getAuthor("jennifer-smith", params);
Author author = authorResponse.getData();
System.out.println(author.getBio());

Categories

import com.buttercms.model.Category;
import com.buttercms.model.CategoriesResponse;
import com.buttercms.model.CategoryResponse;

Map<String, String> params = new HashMap<>();
params.put("include", "recent_posts");

// List all categories
CategoriesResponse categoriesResponse = client.getCategories(params);

for (Category category : categoriesResponse.getData()) {
    System.out.println(category.getName());
    System.out.println(category.getSlug());
}

// Fetch a single category
CategoryResponse categoryResponse = client.getCategory("news", params);

Tags

import com.buttercms.model.Tag;
import com.buttercms.model.TagsResponse;
import com.buttercms.model.TagResponse;

Map<String, String> params = new HashMap<>();
params.put("include", "recent_posts");

// List all tags
TagsResponse tagsResponse = client.getTags(params);

for (Tag tag : tagsResponse.getData()) {
    System.out.println(tag.getName());
}

// Fetch a single tag
TagResponse tagResponse = client.getTag("featured", params);

Query parameters reference

Parameter	Applies To	Description
page	Posts, Pages	Page number for pagination
page_size	Posts, Pages	Number of items per page
exclude_body	Posts	Exclude post body for faster response
author_slug	Posts	Filter posts by author
category_slug	Posts	Filter posts by category
tag_slug	Posts	Filter posts by tag
include	Authors, Categories, Tags	Include recent_posts with response
locale	Pages, Collections	Locale code for localized content
preview	Pages	Set to 1 to include draft content
levels	Pages	Depth of nested references (1-3)

Complete example

import com.buttercms.ButterCMSClient;
import com.buttercms.IButterCMSClient;
import com.buttercms.model.*;
import java.util.*;

public class ButterCMSExample {

    public static void main(String[] args) {
        String apiToken = System.getenv("BUTTERCMS_API_TOKEN");
        IButterCMSClient client = new ButterCMSClient(apiToken);

        try {
            // Fetch the home page
            Map<String, String> pageParams = new HashMap<>();
            pageParams.put("locale", "en");
            Page homePage = client.getPage("landing_page", "home", pageParams);
            System.out.println("Page headline: " + homePage.getFields().get("headline"));

            // Fetch navigation collection
            CollectionResponse collections = client.getCollection(
                Arrays.asList("main_navigation"),
                new HashMap<>()
            );
            List<Map<String, Object>> navItems = collections.getData().get("main_navigation");
            System.out.println("Navigation items: " + navItems.size());

            // Fetch recent blog posts
            Map<String, String> postParams = new HashMap<>();
            postParams.put("page", "1");
            postParams.put("page_size", "3");
            postParams.put("exclude_body", "true");

            PostsResponse postsResponse = client.getPosts(postParams);
            System.out.println("Recent posts: " + postsResponse.getData().size());

            for (Post post : postsResponse.getData()) {
                System.out.println("  - " + post.getTitle());
            }

        } catch (Exception e) {
            System.err.println("Error fetching content: " + e.getMessage());
        }
    }
}

Resources

GitHub Repository

View source code, report issues, and contribute

Maven Central

Package details and version history