{"id":19335709,"url":"https://github.com/buttercms/buttercms-java","last_synced_at":"2025-04-23T00:32:08.981Z","repository":{"id":40562720,"uuid":"167218094","full_name":"ButterCMS/buttercms-java","owner":"ButterCMS","description":"Java SDK for ButterCMS (https://buttercms.com)","archived":false,"fork":false,"pushed_at":"2024-12-13T14:48:29.000Z","size":142,"stargazers_count":1,"open_issues_count":1,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-20T23:04:23.141Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ButterCMS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-23T16:48:14.000Z","updated_at":"2024-12-13T14:48:21.000Z","dependencies_parsed_at":"2024-06-22T03:37:12.413Z","dependency_job_id":"d29f24e4-f300-4f3f-9163-5c3d47a65a70","html_url":"https://github.com/ButterCMS/buttercms-java","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ButterCMS","download_url":"https://codeload.github.com/ButterCMS/buttercms-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250348329,"owners_count":21415894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T03:08:33.286Z","updated_at":"2025-04-23T00:32:08.948Z","avatar_url":"https://github.com/ButterCMS.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# buttercms-java\n\nJava Library for ButterCMS API. \n\n## Documentation\n\nFor a comprehensive list of examples, check out the [API documentation](https://buttercms.com/docs/api/).\n\n\n## Installation\n\n### Maven\n\n\u003c!-- {x-release-please-start-version} --\u003e\n**pom.xml**\n```xml\n\u003cdependencies\u003e\n...\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.buttercms\u003c/groupId\u003e\n      \u003cartifactId\u003ebuttercmsclient\u003c/artifactId\u003e\n      \u003cversion\u003e1.13.0\u003c/version\u003e\n    \u003c/dependency\u003e\n...\n\u003c/dependencies\u003e    \n```\n\u003c!-- {x-release-please-end} --\u003e\n\n### Gradle\n\n\u003c!-- {x-release-please-start-version} --\u003e\n**build.gradle**\n```\ndependencies {\n    implementation 'com.buttercms:buttercmsclient:1.13.0'\n}\n```\n\u003c!-- {x-release-please-end} --\u003e\n\n\n## Usage\n\nTo get started with the Butter API, instantiate the ButterCMSClient with the API key found in the [Butter Admin Settings](https://buttercms.com/settings/) \nand a boolean to specify whether preview mode is enabled. Preview mode enabled will return items saved as drafts.\nAn 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.\n\n```java\nimport com.buttercms.IButterCMSClient;\nimport com.buttercms.ButterCMSClient;\n...\nIButterCMSClient client = new ButterCMSClient(\"your_api_token\", isPreviewEnabled);\n```\n\nIf the application will be making many Butter API calls, it is recommended to store and re-use the client object.\n\nGiven 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:\n```java\nimport com.buttercms.IButterCMSClient;\nimport com.buttercms.ButterCMSClient;\nimport org.apache.http.client.HttpClient;\n...\nHttpClient you_http_client = HttpClients.custom()\n                               .addInterceptorFirst(you_interceptor)\n                               .setDefaultHeaders(you_headers)\n                               .build()\nIButterCMSClient client = new ButterCMSClient(\"your_api_token\", isPreviewEnabled, you_http_client);\n```\n\n## Sections\n\n* [Posts](#posts)\n* [Authors](#authors)\n* [Categories](#categories)\n* [Feeds](#feeds)\n* [Collections](#collections)\n* [Tags](#tags)\n* [Pages](#pages)\n* [Class Definitions](#class-definitions)\n* [Exceptions](#exceptions)\n\n## Posts\n\n### Get Posts\n\nListing posts returns a [PostsResponse](#postsresponse-class) object. This object consists of a [PaginationMeta](#paginationmeta-class) object and List\u0026lt;[Post](#post-class)\u0026gt;\n\n#### getPosts() parameters\n| Parameter|Description|\n| ---|---|\n| queryParams  | Map of additional Query Parameters|\n\n#### getPosts() Query Parameters\n\n| Query Parameter|Default|Description|\n| ---|---|---|\n| page(optional) | 1 | Used to paginate through older posts. |\n| page_size(optional) | 10 |  Used to set the number of blog posts shown per page. |\n| 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. |\n|author_slug(optional) | |Filter posts by an author’s slug.|\n|category_slug(optional) | | Filter posts by a category’s slug.\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"exclude_body\",\"true\");\n    ...\n}}\nPostsResponse posts = butterClient.getPosts(queryParams);\n```\n\n### Retrieving a Single Post\n\nRetrieving 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.\n\n#### getPost() Parameters\n\n| Parameter|Description|\n| ---|---|\n| slug|The slug of the post to be retrieved.|\n\n#### Examples\n\n```java\nPostResponse controversialPost = butterClient.getPost(\"tabs-vs-spaces-throwdown\");\n```\n\n### Searching posts\n\nSearching posts will return a PostsResponseObject [PostsResponse](#postsresponse-class) object. This object consists of a [PaginationMeta](#paginationmeta-class) object and List\u0026lt;[Post](#post-class)\u0026gt;\n\n#### getSearchPosts() parameters\n\n| Parameter|Description|\n| ---|---|\n| queryParams  | Map of additional Query Parameters|\n\n#### getSearchPosts() Query Parameters\n\n| Query Parameter|Default|Description|\n| ---|---|---|\n| query |   | Search query |\n| page(optional) | 1 | Used to paginate through older posts. |\n| page_size(optional) | 10 |  Used to set the number of blog posts shown per page. \n\n#### Example\n\n```\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\nput(\"query\", \"search query\");\n...\n}}\nPostsResponse posts = butterClient.getSearchPosts(queryParams);\n```\n\n## Authors\n\n### List Authors\n\nListing posts returns a [AuthorsResponse](#authorsresponse-class) object. This object consists of a List\u0026lt;[Author](#author-class)\u0026gt;\n\n#### getAuthors() Parameters\n| Parameter|Description|\n| ---|---|\n| queryParams | Map of additional Query Parameters|\n\n#### getAuthors() Query Parameters\n| Query Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`, will return the author's recent posts in the response|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nAuthorsResponse authors = butterClient.getAuthors(queryParams);\n```\n\n### Retrieve a Single Author\n\nRetrieving an author returns an [AuthorResponse](#authorresponse-class) object. This object consists of single [Author](#author-class) if found\n\n#### getAuthor() Parameters\n\n| Parameter|Description|\n| ---|---|\n|slug|The slug of the author to be retrieved.|\n| queryParams | Map of additional Query Parameters|\n\n#### getAuthor() QueryParameters\n| Query Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`, will return the author's recent posts in the response|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nAuthorResponse authors = butterClient.getAuthor(\"john\",queryParams);\n```\n\n## Categories\n\n### List Categories\n\nListing Categories returns a [CategoriesResponse](#categoriesresponse-class) object. This object consists of a List\u0026lt;[Category](#Category-class)\u0026gt;\n\n#### getCategories() Parameters\n| Parameter|Description|\n| ---|---|\n| queryParams | Map of additional Query Parameters|\n\n#### getCategories() Parameters\n\n| Query Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`,  will return recent posts along with categories|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nCategoriesResponse getCategories = butterClient.getCategories(queryParams);\n```\n\n### Retrieve a Single Category\n\nRetrieving an author returns an [CategoryResponse](#categoryresponse-class) object. This object consists of single [Category](#category-class) if found\n\n#### getCategory() Parameters\n\n| Parameter|Description|\n| ---|---|\n|slug|The slug of the category to be retrieved.|\n| queryParams | Map of additional Query Parameters|\n\n\n| Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`,  will return recent posts along with categories|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nCategoryResponse getCategories = butterClient.getCategory(\"java\",queryParams);\n```\n\n## Tags\n\n### List Tags\n\nListing Tags returns a [TagsResponse](#tagsresponse-class) object. This object consists of a List\u0026lt;[Tag](#Tag-class)\u0026gt;\n\n#### getTags() Parameters\n| Parameter|Description|\n| ---|---|\n| queryParams | Map of additional Query Parameters|\n\n#### getTags() Parameters\n\n| Query Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`,  will return recent posts along with tags|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nTagsResponse getTags = butterClient.getTags(queryParams);\n```\n\n### Retrieve a Single Tag\n\nRetrieving an author returns an [TagResponse](#tagresponse-class) object. This object consists of single [Tag](#tag-class) if found\n\n#### getTag() Parameters\n\n| Parameter|Description|\n| ---|---|\n|slug|The slug of the tag to be retrieved.|\n| queryParams | Map of additional Query Parameters|\n\n\n| Parameter|Description|\n| ---|---|\n| include |If value is `recent_posts`,  will return recent posts along with tag|\n\n#### Examples\n\n```java\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\n    put(\"include\",\"recent_posts\");\n    ...\n}}\nTagResponse getTag = butterClient.getTag(\"java\",queryParams);\n```\n\n## Feeds\n\nEach of the feeds methods returns a [Document](https://docs.oracle.com/javase/7/docs/api/org/w3c/dom/Document.html).\n\n\n### RSS Feed\n\nRetrieve a fully generated RSS feed for your blog.\n\n#### Examples\n\n```java\n Document rssFeed = butterClient.getRSS();\n```\n\n### Atom Feed\n\nRetrieve a fully generated Atom feed for your blog.\n\n#### Examples\n\n```java\n Document atomFeed = butterClient.getAtom();\n```\n\n### Sitemap\n\nRetrieve a fully generated sitemap for your blog.\n\n#### Examples\n\n```java\n XmlDocument siteMap = butterClient.getSiteMap();\n```\n\n## Collections\n\n### List collection items\nListing collection items returns a [CollectionResponse\u0026lt;T\u0026gt;](#collectionresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) object and [Collection\u0026lt;T\u0026gt;](#collection-class);\n#### getCollection() Parameters\n\n| Parameter|Description|\n| ---|---|\n|collectionSlug| Collection key|\n| queryParams | Map of additional Query Parameters|\n| classType | Class that collection will be deserialized in to|\n\n#### getCollection() Query Parameters\n\n|Query Parameter|Description|\n| ---|---|\n| fields.key (optional) | Optional param. Filter the result set by the field and value.|\n| order (optional)| Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published|\n| page (optional)| Used for Paginating through result set.|\n| page_size (optional)| Used for Paginating. Defines the number of results returned.|\n| locale (optional)| Set to the api slug of your configured locale (i.e. en or fr)|\n| levels (optional)| Defaults to 2. Defines the levels of relationships to serialize.|\n\n#### Examples\n\n```java\nCollectionResponse response = client.getCollection(\"cars\", new HashMap\u003cString, String\u003e() {{\n            put(\"fields.weight\", \"400\");\n            put(\"page_size\", \"1\");\n    }}, Car.class);\n```\n\n## Pages\n\n### List Pages\n\nListing Pages returns a [PagesResponse\u0026lt;T\u0026gt;](#pagesresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) object and List\u0026lt;T\u0026gt;\n\n#### ListPages() Parameters\n\n| Parameter|Description|\n| ---|---|\n| queryParams | Map of additional Query Parameters|\n| classType | Class that Page will be deserialized in to|\n\n|Query Parameter|Description|\n| ---|---|\n| fields.key (optional) | Optional param. Filter the result set by the field and value.|\n| order (optional)| Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published|\n| page (optional)| Used for Paginating through result set.|\n| page_size (optional)| Used for Paginating. Defines the number of results returned.|\n| locale (optional)| Set to the api slug of your configured locale (i.e. en or fr)|\n| levels (optional)| Defaults to 2. Defines the levels of relationships to serialize.|\n\n#### Examples\n\n```java\nPagesResponse\u003cRecipePage\u003e response = client.getPages(\"recipe\", new HashMap\u003cString, String\u003e() {{\n            put(\"page_size\", \"1\");\n    }}, RecipePage.class)\n```\n\n### Retrieve a Single Page\n\nRetrieving a single page returns a [PageResponse\u0026lt;T\u0026gt;](#pageresponse-class) object\n\n#### getPage() Parameters\n\n| Parameter|Description|\n| ---|---|\n|pageType| Desired page type|\n|pageSlug| Slug of the desired page|\n| queryParams | Map of additional Query Parameters|\n| classType | Class that Page will be deserialized in to|\n\n|Query Parameter|Description|\n| ---|---|\n|locale (optional)| Set to the api slug of your configured locale (i.e. en or fr)|\n\n#### Examples\n\n```java\n   PageResponse\u003cRecipePage\u003e recipe = client.getPage(\"recipe\", \"recipe-page-11\", new HashMap\u003cString, String\u003e() {{\n            put(\"locale\", \"en\");\n    }}, RecipePage.class);\n```\n\n### Search Pages\n\nListing Pages returns a [PagesResponse\u0026lt;T\u0026gt;](#pagesresponse-class) object. This object consists of a [PaginationMeta](#pagination-meta) object and List\u0026lt;T\u0026gt;\n\n#### getSearchPages() parameters\n\n| Parameter|Description|\n| ---|---|\n| pageTypeSlug | The slug of the type of pages you want to retrieve |\n| queryParams | Map of additional Query Parameters|\n| classType | Class that Page will be deserialized in to|\n\n#### getSearchPages() query parameters\n\n|Query Parameter|Description|\n| ---|---|\n| query | Search query |\n|preview (optional)| Set to 1 to return the latest draft version of a page.|\n| fields.key (optional) | Optional param. Filter the result set by the field and value.|\n| order (optional)| Order the result set by this field. Defaults to Ascending. Preprend ’-’ to sort Descending. i.e. order=-date_published|\n| page (optional)| Used for Paginating through result set.|\n| page_size (optional)| Used for Paginating. Defines the number of results returned.|\n| locale (optional)| Set to the api slug of your configured locale (i.e. en or fr)|\n| levels (optional)| Defaults to 2. Defines the levels of relationships to serialize.|\n\n#### Examples\n\n```\nMap\u003cString,String\u003e queryParams = new HashMap\u003cString,String\u003e(){{\nput(\"query\", \"search query\");\n...\n}}\nPagesResponse posts = butterClient.getSearchPages(queryParams);\n```\n\n##### Page Type Definition in the Butter Admin\n\n![alt text](./Examples/RecipePageType.png \"Page Type Definition\")\n\n## Class Definitions\n\n### PostsResponse Class\n\n| Property | Type|\n|----|---|\n|meta| [PaginationMeta](#paginationmeta-class)|\n|data| List\u0026lt;[Post](#post-class)\u0026gt;|\n\n### Post Class\n\n| Property | Type|\n|----|---|\n|url|String|\n|created|Date|\n|published|Date|\n|scheduled|Date|\n|Author|[Author](#author-class)|\n|Categories|List\u0026lt;[Category](#category-class)\u0026gt;|\n|Tags|List\u0026lt;[Tag](#tag-class)\u0026gt;|\n|slug|String|\n|title|String|\n|body|String|\n|summary|String|\n|seoTitle|String|\n|metaDescription|String|\n|featuredImage|String|\n|featuredImageAlt|String|\n|Status|[Status](#status-enum)|\n\n### Status enum\n\n|Constant|Value|\n|---|---|\n|Draft|1|\n|Published|2|\n|Scheduled|3|\n\n### PostResponse Class\n\n| Property | Type|\n|----|---|\n|Meta|[PostMeta](#postmeta-class)|\n|Data|[Post](#post-class)|\n\n### PostMeta Class\n\n| Property | Type|\n|----|---|\n|nextPost|[PostSummary](#postsummary-class)|\n|previousPost|[PostSummary](#postsummary-class)|\n\n### PostSummary Class\n\n| Property | Type|\n|----|---|\n|slug|string|\n|title|string|\n|featuredImage|string|\n\n### AuthorsResponse class\n| Property | Type|\n|----|---|\n|data| List\u0026lt;[Author](#author-class)\u0026gt;|\n\n\n### AuthorResponse class\n| Property | Type|\n|----|---|\n|data| [Author](#author-class)|\n\n### Author Class\n\n| Property | Type|\n|----|---|\n|firstName| string|\n|lastName| string|\n|email| string|\n|slug| string|\n|bio| string|\n|title| string|\n|linkedinUrl| string|\n|facebookUrl| string|\n|instagramUrl| string|\n|pinterestUrl| string|\n|twitterHandle| string|\n|profileImage| string|\n|recentPosts| List\u0026lt;[Post](#post-class)\u0026gt;|\n\n\n### CategoriesResponse class\n| Property | Type|\n|----|---|\n|data| List\u0026lt;[Category](#author-class)\u0026gt;|\n\n\n\n### CategoryResponse class\n| Property | Type|\n|----|---|\n|data| [Category](#author-class)|\n\n### Category Class\n\n| Property | Type|\n|----|---|\n|name| string|\n|slug| string|\n|recentPosts| IEnumerable\u0026lt;[Post](#post-class)\u0026gt;|\n\n### TagsResponse class\n| Property | Type|\n|----|---|\n|data| List\u0026lt;[Tag](#tag-class)\u0026gt;|\n\n\n\n### TagResponse class\n| Property | Type|\n|----|---|\n|data| [Tag](#tag-class)|\n\n### Tag Class\n\n| Property | Type|\n|----|---|\n|name| string|\n|slug| string|\n|recentPosts| IEnumerable\u0026lt;[Post](#post-class)\u0026gt;|\n\n\n### CollectionResponse class\n| Property | Type|\n|----|---|\n|data| [Collection\u0026lt;T\u0026gt;](#collection-class)|\n|meta| [PaginationMeta](#paginationmeta-class)|\n\n### Collection class\n| Property | Type|\n|----|---|\n|items| List\u0026lt;T\u0026gt;|\n\n### PagesResponse Class\n\n| Property | Type|\n|----|---|\n|meta| [PageMeta](#pagemeta-class)|\n|data| List\u0026lt;[Page](#page-class)\u0026lt;T\u0026gt;\u0026gt;|\n\n### PaginationMeta Class\n\n| Property | Type|\n|----|---|\n|count| int|\n|previousPage| int|\n|nextPage| int|\n\n### PageResponse Class\n\n| Property | Type|\n|----|---|\n|data| [Page](#page-class)\u0026lt;T\u0026gt;|\n\n### Page Class\n\n| Property | Type|\n|----|---|\n|slug| string|\n|pageType|string|\n|fields|T|\n|status|[Status](#status-enum)|\n|scheduled|Date|\n\n## Exceptions\n\n### ButterCMSResponseException\n\nGeneral RunTime exception that wraps API error responses \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercms%2Fbuttercms-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuttercms%2Fbuttercms-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercms%2Fbuttercms-java/lists"}