Android library for ButterCMS API.
For a comprehensive list of examples, check out the API documentation.
build.gradle
dependencies {
implementation "com.buttercms.android:buttercmsclient-kotlin:1.0.0"
}
- Authors
- Categories
- Collections
- Pages
- Posts
- Tags
To get started with the Butter API, instantiate the ButterCMSClient with the API key found in the Butter Admin Settings.
// Initialize Butter client
val client = ButterCMS("your_api_key")
API calls take map of parameters. Parameters are specified by user according to documentation - check Butter API doc Api Calls are asynchronous and expect Callback as a parameter. Callback provides result when API call is finished.
Example of calling API:
val client = ButterCMS("your_api_key")
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getAuthor(
"author", queryParameters,
callback = object :
Callback<Author, RestCallError> {
override fun success(response: Author) {
//do something on success
Log.w("success", response.toString())
}
override fun failure(error: RestCallError) {
//do something on failure
Log.w("error", error.errorMessage.toString() + error.errorBody.toString())
}
})
getPosts() parameters:
| Parameter | Description |
|---|---|
| queryParameters | Map of additional query parameters |
getPosts() queryParameters
| QueryParameter | 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 |
| author_slug (optional) | Filter posts by an author’s slug | |
| category_slug(optional) | Filter posts by a category’s slug | |
| query | Search query |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["page"] = "1"
queryParameters["page_size"] = "10"
client.data.getPosts(
queryParameters,
callback = object : Callback<Posts, RestCallError> {
override fun success(response: Posts) {}
override fun failure(error: RestCallError) {}
})
getPost() parameters
| Parameter | Description |
|---|---|
| slug | The slug of the post to be retrieved |
Example:
client.data.getPost( "example-2",
callback = object : Callback<Post, RestCallError> {
override fun success(response: Post) {}
override fun failure(error: RestCallError) {}
}
)
getAuthors() parameters
| Parameter | Description |
|---|---|
| queryParameters | Map of additional query parameters |
getAuthors() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return author's recent posts in response |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getAuthors(
queryParameters,
callback = object :
Callback<Authors, RestCallError> {
override fun success(response: Authors) {}
override fun failure(error: RestCallError) {}
}
)
getAuthor() parameters
| Parameter | Description |
|---|---|
| slug | Slug of author to be retrieved |
| queryParameters | Map of additional query parameters |
getAuthor() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return author's recent posts in response |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getAuthors(
"john",
queryParameters,
callback = object :
Callback<Authors, RestCallError> {
override fun success(response: Authors) {}
override fun failure(error: RestCallError) {}
}
)
getCategories() parameters
| Parameter | Description |
|---|---|
| queryParameters | Map of additional query parameters |
getCategories() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return recent posts along with categories |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getCategories(
queryParameters,
callback = object :
Callback<Categories, RestCallError> {
override fun success(response: Categories) {}
override fun failure(error: RestCallError) {}
}
)
getCategory() parameters
| Parameter | Description |
|---|---|
| slug | Slug of the category to be retrieved |
| queryParameters | Map of additional query parameters |
getCategory() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return recent posts along with categories |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getCategory(
"example-category", queryParameters,
callback = object :
Callback<Category, RestCallError> {
override fun success(response: Category) {}
override fun failure(error: RestCallError) {}
}
)
getTags() parameters
| Parameter | Description |
|---|---|
| queryParameters | Map of additional query parameters |
getTags() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return recent posts along with categories |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getTags(
queryParameters,
callback = object : Callback<Tags, RestCallError> {
override fun success(response: Tags) {}
override fun failure(error: RestCallError) {}
}
)
getTag() parameters
| Parameter | Description |
|---|---|
| slug | Slug of the tag to be retrieved |
| queryParameters | Map of additional query parameters |
getTag() queryParameters
| QueryParameter | Description |
|---|---|
| include | If value is recent_posts, will return recent posts along with categories |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["include"] = "recent_posts"
client.data.getTag(
"example-tag", queryParameters,
callback = object : Callback<Tag, RestCallError> {
override fun success(response: Tag) {}
override fun failure(error: RestCallError) {}
}
)
The Pages in Butter CMS has configurable schema. See ButterCMS doc for details how to create page. The schema defines fields which can exist on the page.
ButerCMS also provides a concept of Page types and you can get all pages of the same type by getPages() API. To read more about the Page types refer to ButterCMS doc.
SDK requires you to model Page schema as data class and pass as parameter to getPages() func. Data class needs to have schema as PageItem. This allows SDK deserialize page data for you. [check example - DemoPage.kt]
getPages() parameters
| Parameter | Description |
|---|---|
| pageType | Type of pages to be retrieved |
| queryParameters | Map of additional query parameters |
| classType. | Class that Page will be deserialized in to |
getPages() queryParameters
| QueryParameter | 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 Asc. '-' to sort Desc |
| 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 |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["locale"] = "en"
queryParameters["preview"] = "1"
client.data.getPages(
"homepage",
queryParameters,
DemoPageItem::class.java,
callback = object : Callback<Pages, RestCallError> {
override fun success(response: Pages) {}
override fun failure(error: RestCallError) {}
}
)
getPage() parameters
| Parameter | Description |
|---|---|
| pageType | Type of page to be retrieved |
| pageSlug | Slug of page to be retrieved |
| queryParameters | Map of additional query parameters |
| classType | Class that Page will be deserialized in to |
getPage() queryParameters
| QueryParameter | 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) |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["locale"] = "en"
queryParameters["preview"] = "1"
client.data.getPage(
"homepage",
"homepage",
queryParameters,
DemoPageItem::class.java,
callback = object : Callback<Page, RestCallError> {
override fun success(response: Page) {}
override fun failure(error: RestCallError) {}
}
)
similar as Pages the Collections has also configurable schema. See ButterCMS doc for more details. The schema again define fields which composes the collection item. SDK requires you to model the collection data as a data class and pass as parameter to getCollection func. [check example DemoCollection.kt]
getCollection() parameters
| Parameter | Description |
|---|---|
| slug | collection key |
| queryParameters | Map of additional query parameters |
| classType | Class that Colection will be deserialized to |
getCollection() queryParameters
| QueryParameter | 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 Asc. '-' to sort Desc |
| 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 |
Example:
val queryParameters = HashMap<String, String>()
queryParameters["locale"] = "en"
client.data.getCollection(
"faq",
queryParameters,
DemoData::class.java,
callback = object :
Callback<Collections, RestCallError> {
override fun success(response: Collections) {}
override fun failure(error: RestCallError) {}
}
)