com.sparkpost.package-info Maven / Gradle / Ivy
/**
* com.sparkpost provides an interface to the SparkPost
* REST API.
*
* This java API is designed to follow closely the design of the SparkPost
* REST API. As a result, this java library is composed of 3 groups of java classes:
*
* - com.sparkpost.resources.ResourceXXX classes
*
- com.sparkpost.model classes (Data Transfer Objects)
*
- REST mechanism classes.
*
*
*
* Resources classes
* A resource class is a collection of static methods under one class.
* All of the methods are a 1-to-1 match with an endpoint within a SparkPost REST API.
*
* For instance, the ResourceTransmissions class contains 3 methods:
*
* - create() matches the create endpoint in the transmission API
*
- retrieve() matches the retrieve endpoint in the transmission API
*
- list() matches the list endpoint in the transmission API
*
* See the
* SparkPost Transmission API.
*
* Data Transfer Objects
* A DTO class is a container of fields which intent is to be serialized into
* a JSON string when sending a request to a SparkPost API.
*
* For instance, the Sending Domains resource ( class ResourceSendingDomains )
* has a create() method that matches the create endpoint in the SparkPost
* Sending Domains API.
* To create a domain, the JSON request to the SparkPost API is made of 2 fields:
*
* - the domain name
*
- the DKIM information
*
* We could have designed this java library to merely accept these fields in the
* method signature , for instance here ResourceSendingDomains.create would
* have become ResourceSendingDomains.create( String domain, String dkim_info).
* Only in most cases the request parameters are numerous, and passing them
* directly as method parameter would become very cumbersome.
* Instead we use DTOs which represent *exactly* how the JSON request is expressed.
* As a result, in this example, the create method's signature is :
* ResourceSendingDomains.create( RestConnection connection, SendingDomain domain)
* (connection is the server connection to use to make the request, see below)
*
* REST mechanism classes
* There are 4 classes necessary to put in place our REST system :
*
* - Client
*
- RestConnection
*
- Response
*
- SparkPostException
*
*
* Client define information specific to the SparkPost client: the
* authorization key and the from email.
* The RestConn does all of the work : it sends requests and receives responses
* from the SparkPost server. All of the resources methods (see above) take
* for first parameter an RestConnection object.
* The Response class describes a response received by the SparkPost server.
* And finally the SparkPostException is the custom exception for this library.
*
*
* See The SampleApplication class for an example of creating a template,
* storing it, and creating a transmission with it.
* It also implements a simple JSON-to-Java deserialization using Google's
* Gson class.
*/
package com.sparkpost ;