https://github.com/buttercms/buttercms-java

Java SDK for ButterCMS (https://buttercms.com)
https://github.com/buttercms/buttercms-java
Last synced: about 1 year ago
JSON representation
Java SDK for ButterCMS (https://buttercms.com)
Host: GitHub
URL: https://github.com/buttercms/buttercms-java
Owner: ButterCMS
License: mit
Created: 2019-01-23T16:48:14.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2024-12-13T14:48:29.000Z (over 1 year ago)
Last Synced: 2025-04-20T23:04:23.141Z (about 1 year ago)
Language: Java
Homepage:
Size: 139 KB
Stars: 1
Watchers: 8
Forks: 3
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

README

          # buttercms-java

Java Library for ButterCMS API. 

## Documentation

For a comprehensive list of examples, check out the [API documentation](https://buttercms.com/docs/api/).

## Installation

### Maven

**pom.xml**

```xml

...

    

      com.buttercms

      buttercmsclient

      1.13.0

    

...

    

```

### Gradle

**build.gradle**

```

dependencies {

    implementation 'com.buttercms:buttercmsclient:1.13.0'

}

```

## Usage

To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the [Butter Admin Settings](https://buttercms.com/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](https://msdn.microsoft.com/en-us/library/system.timespan%28v=vs.110%29.aspx); the default is 10 seconds.

```java

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](https://hc.apache.org/) - meaning, in case you need more custom setting for `HttpClient` you can pass one in to constructor:

```java

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](#posts)

* [Authors](#authors)

* [Categories](#categories)

* [Feeds](#feeds)

* [Collections](#collections)

* [Tags](#tags)

* [Pages](#pages)

* [Class Definitions](#class-definitions)

* [Exceptions](#exceptions)

## Posts

### Get Posts

Listing posts returns a [PostsResponse](#postsresponse-class) object. This object consists of a [PaginationMeta](#paginationmeta-class) object and List<[Post](#post-class)>

#### 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

```java

Map queryParams = new HashMap(){{

    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](#post-class) and [PostMetadata](#postmeta-class). Post Metadata offers hints about the Previous and Next posts.

#### getPost() Parameters

| Parameter|Description|

| ---|---|

| slug|The slug of the post to be retrieved.|

#### Examples

```java

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

```

### Searching posts

Searching posts will return a PostsResponseObject [PostsResponse](#postsresponse-class) object. This object consists of a [PaginationMeta](#paginationmeta-class) object and List<[Post](#post-class)>

#### 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 queryParams = new HashMap(){{

put("query", "search query");

...

}}

PostsResponse posts = butterClient.getSearchPosts(queryParams);

```

## Authors

### List Authors

Listing posts returns a [AuthorsResponse](#authorsresponse-class) object. This object consists of a List<[Author](#author-class)>

#### 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

AuthorsResponse authors = butterClient.getAuthors(queryParams);

```

### Retrieve a Single Author

Retrieving an author returns an [AuthorResponse](#authorresponse-class) object. This object consists of single [Author](#author-class) 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

AuthorResponse authors = butterClient.getAuthor("john",queryParams);

```

## Categories

### List Categories

Listing Categories returns a [CategoriesResponse](#categoriesresponse-class) object. This object consists of a List<[Category](#Category-class)>

#### 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

CategoriesResponse getCategories = butterClient.getCategories(queryParams);

```

### Retrieve a Single Category

Retrieving an author returns an [CategoryResponse](#categoryresponse-class) object. This object consists of single [Category](#category-class) 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

CategoryResponse getCategories = butterClient.getCategory("java",queryParams);

```

## Tags

### List Tags

Listing Tags returns a [TagsResponse](#tagsresponse-class) object. This object consists of a List<[Tag](#Tag-class)>

#### 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

TagsResponse getTags = butterClient.getTags(queryParams);

```

### Retrieve a Single Tag

Retrieving an author returns an [TagResponse](#tagresponse-class) object. This object consists of single [Tag](#tag-class) 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

```java

Map queryParams = new HashMap(){{

    put("include","recent_posts");

    ...

}}

TagResponse getTag = butterClient.getTag("java",queryParams);

```

## Feeds

Each of the feeds methods returns a [Document](https://docs.oracle.com/javase/7/docs/api/org/w3c/dom/Document.html).

### RSS Feed

Retrieve a fully generated RSS feed for your blog.

#### Examples

```java

 Document rssFeed = butterClient.getRSS();

```

### Atom Feed

Retrieve a fully generated Atom feed for your blog.

#### Examples

```java

 Document atomFeed = butterClient.getAtom();

```

### Sitemap

Retrieve a fully generated sitemap for your blog.

#### Examples

```java

 XmlDocument siteMap = butterClient.getSiteMap();

```

## Collections

### List collection items

Listing collection items returns a [CollectionResponse<T>](#collectionresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) object and [Collection<T>](#collection-class);

#### 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

```java

CollectionResponse response = client.getCollection("cars", new HashMap() {{

            put("fields.weight", "400");

            put("page_size", "1");

    }}, Car.class);

```

## Pages

### List Pages

Listing Pages returns a [PagesResponse<T>](#pagesresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) 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

```java

PagesResponse response = client.getPages("recipe", new HashMap() {{

            put("page_size", "1");

    }}, RecipePage.class)

```

### Retrieve a Single Page

Retrieving a single page returns a [PageResponse<T>](#pageresponse-class) 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

```java

   PageResponse recipe = client.getPage("recipe", "recipe-page-11", new HashMap() {{

            put("locale", "en");

    }}, RecipePage.class);

```

### Search Pages

Listing Pages returns a [PagesResponse<T>](#pagesresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) 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 queryParams = new HashMap(){{

put("query", "search query");

...

}}

PagesResponse posts = butterClient.getSearchPages(queryParams);

```

##### Page Type Definition in the Butter Admin

![alt text](./Examples/RecipePageType.png "Page Type Definition")

## Class Definitions

### PostsResponse Class

| Property | Type|

|----|---|

|meta| [PaginationMeta](#paginationmeta-class)|

|data| List<[Post](#post-class)>|

### Post Class

| Property | Type|

|----|---|

|url|String|

|created|Date|

|published|Date|

|scheduled|Date|

|Author|[Author](#author-class)|

|Categories|List<[Category](#category-class)>|

|Tags|List<[Tag](#tag-class)>|

|slug|String|

|title|String|

|body|String|

|summary|String|

|seoTitle|String|

|metaDescription|String|

|featuredImage|String|

|featuredImageAlt|String|

|Status|[Status](#status-enum)|

### Status enum

|Constant|Value|

|---|---|

|Draft|1|

|Published|2|

|Scheduled|3|

### PostResponse Class

| Property | Type|

|----|---|

|Meta|[PostMeta](#postmeta-class)|

|Data|[Post](#post-class)|

### PostMeta Class

| Property | Type|

|----|---|

|nextPost|[PostSummary](#postsummary-class)|

|previousPost|[PostSummary](#postsummary-class)|

### PostSummary Class

| Property | Type|

|----|---|

|slug|string|

|title|string|

|featuredImage|string|

### AuthorsResponse class

| Property | Type|

|----|---|

|data| List<[Author](#author-class)>|

### AuthorResponse class

| Property | Type|

|----|---|

|data| [Author](#author-class)|

### 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](#post-class)>|

### CategoriesResponse class

| Property | Type|

|----|---|

|data| List<[Category](#author-class)>|

### CategoryResponse class

| Property | Type|

|----|---|

|data| [Category](#author-class)|

### Category Class

| Property | Type|

|----|---|

|name| string|

|slug| string|

|recentPosts| IEnumerable<[Post](#post-class)>|

### TagsResponse class

| Property | Type|

|----|---|

|data| List<[Tag](#tag-class)>|

### TagResponse class

| Property | Type|

|----|---|

|data| [Tag](#tag-class)|

### Tag Class

| Property | Type|

|----|---|

|name| string|

|slug| string|

|recentPosts| IEnumerable<[Post](#post-class)>|

### CollectionResponse class

| Property | Type|

|----|---|

|data| [Collection<T>](#collection-class)|

|meta| [PaginationMeta](#paginationmeta-class)|

### Collection class

| Property | Type|

|----|---|

|items| List<T>|

### PagesResponse Class

| Property | Type|

|----|---|

|meta| [PageMeta](#pagemeta-class)|

|data| List<[Page](#page-class)<T>>|

### PaginationMeta Class

| Property | Type|

|----|---|

|count| int|

|previousPage| int|

|nextPage| int|

### PageResponse Class

| Property | Type|

|----|---|

|data| [Page](#page-class)<T>|

### Page Class

| Property | Type|

|----|---|

|slug| string|

|pageType|string|

|fields|T|

|status|[Status](#status-enum)|

|scheduled|Date|

## Exceptions

### ButterCMSResponseException

General RunTime exception that wraps API error responses
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/buttercms/buttercms-java

Awesome Lists containing this project

README
