From 003ccdbdaf7dfcd366084673ee09184cb8af84fd Mon Sep 17 00:00:00 2001 From: Jesse Morgan Date: Sat, 19 Mar 2016 10:30:11 -0700 Subject: Adding README.md --- LICENSE.md | 7 +++++ README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 LICENSE.md create mode 100644 README.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..cde32f0 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,7 @@ +Copyright (c) 2016 Jesse Morgan + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..766431e --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +# ccb-api-client-java + +ccb-api-client-java is a Java library for accessing the +[Church Community Builder][CCB] [API][APIDOCS]. + +This library is not provided nor supported by Church Community Builder. +It was build by Jesse Morgan for use in the [Foursquare GROW][GROW] project +and released with the hopes of helping anyone else using the CCB API. + +Only a few services are currently supported. The client currently supports: + +* `individual_profiles` +* `individual_profile_from_id` +* `individual_profile_from_login_password` +* `individual_profile_from_micr` +* `custom_field_labels` + +Adding new services is relatively easy. Skip down to the Contributing section +if the one you need is missing. + +## Usage + +1. Create a single instance of CCBAPIClient for your application. +CCBAPIClient is thread-safe and manages its own pool of HTTP connections. + +```java +CCBAPI ccbClient = new CCBAPIClient("mychurch", "myuser", "mypassword"); +``` + +2. Call the necessary APIs. For example, to get an individual by id: + +```java +try { + GetIndividualProfilesRequest request = new GetIndividualProfilesRequest() + .withIndividualId(48); + GetIndividualProfilesResponse response = mAPI.getIndividualProfiles(request); +} catch (CCBRetryableErrorException e) { + // TODO: Retry if necessary with an appropriate back-off. +} catch (CCBErrorResponseException e) { + // TODO: Optionally handle error responses from CCB differently than below. +} catch (IOException e) { + // TODO: Handle other errors. +} +``` + +3. Do something useful with the responses from CCB. + +```java +IndividualProfile profile = response.getIndividuals().get(0); +System.out.println(profile.getFullName()); +``` + +## Contributing + +1. Fork it! +2. Create your feature branch: `git checkout -b my-new-feature` +3. Commit your changes: `git commit -am 'Add some feature'` +4. Push to the branch: `git push origin my-new-feature` +5. Submit a pull request + +### Adding New Services + +1. Create the request class. The request class should use a builder pattern to + collect all of the required and optional parameters. For an example, see + [GetIndividualProfilesRequest.java](src/main/java/com/p4square/ccbapi/model/GetIndividualProfilesRequest.java). + +2. Create classes for the response and other models. This is really the hardest + part. For an example see [GetCustomFieldLabelsResponse.java](src/main/java/com/p4square/ccbapi/model/GetCustomFieldLabelsResponse.java) + and [CustomField.java](src/main/java/com/p4square/ccbapi/model/CustomField.java). + +3. Add tests for binding the models. + + 1. Create an XML file from the sample response in the API documentation. + For an example, see [ccb_custom_field_labels_response.xml](src/test/resources/com/p4square/ccbapi/model/ccb_custom_field_labels_response.xml) + + 2. Add a test to verify all the fields bind correctly. + See [GetCustomFieldLabelsResponseTest.java](src/test/java/com/p4square/ccbapi/model/GetCustomFieldLabelsResponseTest.java) + +4. Add methods for the new service to [CCBAPI.java](src/main/java/com/p4square/ccbapi/CCBAPI.java) + and [CCBAPIClient.java](src/main/java/com/p4square/ccbapi/CCBAPIClient.java). + +4. Add tests for your new service to [CCBAPIClientTest.java](src/test/java/com/p4square/ccbapi/CCBAPIClientTest.java). + +## License + +Copyright (c) 2016 Jesse Morgan + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +[CCB]: https://www.churchcommunitybuilder.com/ +[APIDOCS]: https://support.churchcommunitybuilder.com/customer/portal/articles/640589-api-documentation +[GROW]: https://github.com/PuyallupFoursquare/foursquare-grow \ No newline at end of file -- cgit v1.2.3