Giter VIP home page Giter VIP logo

buttercms-java's Introduction

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>1.6</version>
    </dependency>
...
</dependencies>

Gradle

build.gradle

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

Usage

To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings. 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");

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", 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.
query Search query

Examples

Map<String,String> queryParams = new HashMap<String,String>(){{
    add("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");

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>(){{
    add("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>(){{
    add("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>(){{
    add("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>(){{
    add("include","recent_posts");
    ...
}}
CategoryResponse getCategories = butterClient.getCategory("java",queryParams);

Feeds

Each of the feeds methods returns an 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
test (optional) Set to 1 to enable Preview mode for viewing draft content.
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
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

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
preview (optional) Set to 1 to return the latest draft version of a page.
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("preview", "1");
    }}, RecipePage.class);
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>
slug String
title String
body String
summary String
seoTitle String
metaDescription String
featuredImage 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>

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

buttercms-java's People

Contributors

barbarnik avatar jakelumetta avatar

Watchers

avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.