Skip to content

Latest commit

 

History

History
647 lines (470 loc) · 16.3 KB

README.md

File metadata and controls

647 lines (470 loc) · 16.3 KB
Raw

buttercms-java

Java Library for ButterCMS API.

Documentation

For a comprehensive list of examples, check out the API documentation.

Installation

Maven

pom.xml

<dependencies>
...
    <dependency>
      <groupId>com.buttercms</groupId>
      <artifactId>buttercmsclient</artifactId>
      <version>2.1.0</version>
    </dependency>
...
</dependencies>

Gradle

build.gradle

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

Usage

To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings and a boolean to specify whether preview mode is enabled. Preview mode enabled will return items saved as drafts. An optional timeout parameter can be passed as a TimeSpan; the default is 10 seconds.

import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
...
IButterCMSClient client = new ButterCMSClient("your_api_token", isPreviewEnabled);

If the application will be making many Butter API calls, it is recommended to store and re-use the client object.

Given client is based on Apache HttpComponents - meaning, in case you need more custom setting for HttpClient you can pass one in to constructor:

import com.buttercms.IButterCMSClient;
import com.buttercms.ButterCMSClient;
import org.apache.http.client.HttpClient;
...
HttpClient you_http_client = HttpClients.custom()
                               .addInterceptorFirst(you_interceptor)
                               .setDefaultHeaders(you_headers)
                               .build()
IButterCMSClient client = new ButterCMSClient("your_api_token", isPreviewEnabled, you_http_client);

Sections

Posts

Get Posts

Listing posts returns a PostsResponse object. This object consists of a PaginationMeta object and List<Post>

getPosts() parameters

Parameter Description
queryParams Map of additional Query Parameters

getPosts() Query Parameters

Query Parameter Default Description
page(optional) 1 Used to paginate through older posts.
page_size(optional) 10 Used to set the number of blog posts shown per page.
exclude_body(optional) false When true, does not return the full post body. Useful for keeping response size down when showing a list of blog posts.
author_slug(optional) Filter posts by an author’s slug.
category_slug(optional) Filter posts by a category’s slug.

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("exclude_body","true");
    ...
}}
PostsResponse posts = butterClient.getPosts(queryParams);

Retrieving a Single Post

Retrieving a single Post will return a PostResponse object. This object consists of a single Post and PostMetadata. Post Metadata offers hints about the Previous and Next posts.

getPost() Parameters

Parameter Description
slug The slug of the post to be retrieved.

Examples

PostResponse controversialPost = butterClient.getPost("tabs-vs-spaces-throwdown");

Searching posts

Searching posts will return a PostsResponseObject PostsResponse object. This object consists of a PaginationMeta object and List<Post>

getSearchPosts() parameters

Parameter Description
queryParams Map of additional Query Parameters

getSearchPosts() Query Parameters

Query Parameter Default Description
query Search query
page(optional) 1 Used to paginate through older posts.
page_size(optional) 10 Used to set the number of blog posts shown per page.

Example

Map<String,String> queryParams = new HashMap<String,String>(){{
put("query", "search query");
...
}}
PostsResponse posts = butterClient.getSearchPosts(queryParams);

Authors

List Authors

Listing posts returns a AuthorsResponse object. This object consists of a List<Author>

getAuthors() Parameters

Parameter Description
queryParams Map of additional Query Parameters

getAuthors() Query Parameters

Query Parameter Description
include If value is recent_posts, will return the author's recent posts in the response

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
AuthorsResponse authors = butterClient.getAuthors(queryParams);

Retrieve a Single Author

Retrieving an author returns an AuthorResponse object. This object consists of single Author if found

getAuthor() Parameters

Parameter Description
slug The slug of the author to be retrieved.
queryParams Map of additional Query Parameters

getAuthor() QueryParameters

Query Parameter Description
include If value is recent_posts, will return the author's recent posts in the response

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
AuthorResponse authors = butterClient.getAuthor("john",queryParams);

Categories

List Categories

Listing Categories returns a CategoriesResponse object. This object consists of a List<Category>

getCategories() Parameters

Parameter Description
queryParams Map of additional Query Parameters

getCategories() Parameters

Query Parameter Description
include If value is recent_posts, will return recent posts along with categories

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
CategoriesResponse getCategories = butterClient.getCategories(queryParams);

Retrieve a Single Category

Retrieving an author returns an CategoryResponse object. This object consists of single Category if found

getCategory() Parameters

Parameter Description
slug The slug of the category to be retrieved.
queryParams Map of additional Query Parameters
Parameter Description
include If value is recent_posts, will return recent posts along with categories

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
CategoryResponse getCategories = butterClient.getCategory("java",queryParams);

Tags

List Tags

Listing Tags returns a TagsResponse object. This object consists of a List<Tag>

getTags() Parameters

Parameter Description
queryParams Map of additional Query Parameters

getTags() Parameters

Query Parameter Description
include If value is recent_posts, will return recent posts along with tags

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
TagsResponse getTags = butterClient.getTags(queryParams);

Retrieve a Single Tag

Retrieving an author returns an TagResponse object. This object consists of single Tag if found

getTag() Parameters

Parameter Description
slug The slug of the tag to be retrieved.
queryParams Map of additional Query Parameters
Parameter Description
include If value is recent_posts, will return recent posts along with tag

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    put("include","recent_posts");
    ...
}}
TagResponse getTag = butterClient.getTag("java",queryParams);

Feeds

Each of the feeds methods returns a Document.

RSS Feed

Retrieve a fully generated RSS feed for your blog.

Examples

 Document rssFeed = butterClient.getRSS();

Atom Feed

Retrieve a fully generated Atom feed for your blog.

Examples

 Document atomFeed = butterClient.getAtom();

Sitemap

Retrieve a fully generated sitemap for your blog.

Examples

 XmlDocument siteMap = butterClient.getSiteMap();

Collections

List collection items

Listing collection items returns a CollectionResponse<T> object. This object consists of a PaginationMeta object and Collection<T>;

getCollection() Parameters

Parameter Description
collectionSlug Collection key
queryParams Map of additional Query Parameters
classType Class that collection will be deserialized in to

getCollection() Query Parameters

Query Parameter Description
fields.key (optional) Optional param. Filter the result set by the field and value.
order (optional) Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published
page (optional) Used for Paginating through result set.
page_size (optional) Used for Paginating. Defines the number of results returned.
locale (optional) Set to the api slug of your configured locale (i.e. en or fr)
levels (optional) Defaults to 2. Defines the levels of relationships to serialize.

Examples

CollectionResponse response = client.getCollection("cars", new HashMap<String, String>() {{
            put("fields.weight", "400");
            put("page_size", "1");
    }}, Car.class);

Pages

List Pages

Listing Pages returns a PagesResponse<T> object. This object consists of a PaginationMeta object and List<T>

ListPages() Parameters

Parameter Description
queryParams Map of additional Query Parameters
classType Class that Page will be deserialized in to
Query Parameter Description
fields.key (optional) Optional param. Filter the result set by the field and value.
order (optional) Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published
page (optional) Used for Paginating through result set.
page_size (optional) Used for Paginating. Defines the number of results returned.
locale (optional) Set to the api slug of your configured locale (i.e. en or fr)
levels (optional) Defaults to 2. Defines the levels of relationships to serialize.

Examples

PagesResponse<RecipePage> response = client.getPages("recipe", new HashMap<String, String>() {{
            put("page_size", "1");
    }}, RecipePage.class)

Retrieve a Single Page

Retrieving a single page returns a PageResponse<T> object

getPage() Parameters

Parameter Description
pageType Desired page type
pageSlug Slug of the desired page
queryParams Map of additional Query Parameters
classType Class that Page will be deserialized in to
Query Parameter Description
locale (optional) Set to the api slug of your configured locale (i.e. en or fr)

Examples

   PageResponse<RecipePage> recipe = client.getPage("recipe", "recipe-page-11", new HashMap<String, String>() {{
            put("locale", "en");
    }}, RecipePage.class);

Search Pages

Listing Pages returns a PagesResponse<T> object. This object consists of a PaginationMeta object and List<T>

getSearchPages() parameters

Parameter Description
pageTypeSlug The slug of the type of pages you want to retrieve
queryParams Map of additional Query Parameters
classType Class that Page will be deserialized in to

getSearchPages() query parameters

Query Parameter Description
query Search query
preview (optional) Set to 1 to return the latest draft version of a page.
fields.key (optional) Optional param. Filter the result set by the field and value.
order (optional) Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published
page (optional) Used for Paginating through result set.
page_size (optional) Used for Paginating. Defines the number of results returned.
locale (optional) Set to the api slug of your configured locale (i.e. en or fr)
levels (optional) Defaults to 2. Defines the levels of relationships to serialize.

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
put("query", "search query");
...
}}
PagesResponse posts = butterClient.getSearchPages(queryParams);
Page Type Definition in the Butter Admin

alt text

Class Definitions

PostsResponse Class

Property Type
meta PaginationMeta
data List<Post>

Post Class

Property Type
url String
created Date
published Date
Author Author
Categories List<Category>
Tags List<Tag>
slug String
title String
body String
summary String
seoTitle String
metaDescription String
featuredImage String
featuredImageAlt String
Status Status

Status enum

Constant Value
Draft 1
Published 2

PostResponse Class

Property Type
Meta PostMeta
Data Post

PostMeta Class

Property Type
nextPost PostSummary
previousPost PostSummary

PostSummary Class

Property Type
slug string
title string
featuredImage string

AuthorsResponse class

Property Type
data List<Author>

AuthorResponse class

Property Type
data Author

Author Class

Property Type
firstName string
lastName string
email string
slug string
bio string
title string
linkedinUrl string
facebookUrl string
instagramUrl string
pinterestUrl string
twitterHandle string
profileImage string
recentPosts List<Post>

CategoriesResponse class

Property Type
data List<Category>

CategoryResponse class

Property Type
data Category

Category Class

Property Type
name string
slug string
recentPosts IEnumerable<Post>

TagsResponse class

Property Type
data List<Tag>

TagResponse class

Property Type
data Tag

Tag Class

Property Type
name string
slug string
recentPosts IEnumerable<Post>

CollectionResponse class

Property Type
data Collection<T>
meta PaginationMeta

Collection class

Property Type
items List<T>

PagesResponse Class

Property Type
meta PageMeta
data List<Page<T>>

PaginationMeta Class

Property Type
count int
previousPage int
nextPage int

PageResponse Class

Property Type
data Page<T>

Page Class

Property Type
slug string
fields T

Exceptions

ButterCMSResponseException

General RunTime exception that wraps API error responses