User Guide

Introduction

Welcome to PeerAssist’s Application Programming Interface (API)

This documentation is a pre-release outline of all the API functionality that will be offered on our initial release.

This API is intended for use with developers who want to integrate PeerAssist with other applications.It provides access to your data to push and pull from our system into your own systems.

The Peer Assist API is hosted at api.mypeerassist.com

We provide access to our API for our partners and customers upon request.

Please contact [email protected] to find out more on how to get started with our API.

Developer Support

If you run into any issues or have questions on how to use our API, we are happy to help.

Please get in touch by emailing [email protected] and we will be sure to get back to you.

Security

First and foremost, your data security and integrity is our primary concern.

After you have signed up to use the API, we will provide you with an API key to use.

The API key can be used to retrieve the access token that will allow your application can perform all other API requests on behalf of the user.

This API key should be kept as secure as possible and only shared with resources that need to know it. Do not store it in your code or in a location that can be accessed publicly.

Should you suspect that your key has been compromised or if you require a new key, please contact [email protected] and we will reset this and provide you with a new key.

Let's Get Started!

To get started, we would like to outline some of the standard API concepts that are key to developing a successful integration to PeerAssist.

The PeerAssist API is a REST API which defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.

These are the standard methods and their meanings:

Method Name	Action	Description
GET	Read	This request is used to get a resource from a server. If you perform a `GET` request, the server looks for the data you requested and sends it back to you. In other words, a `GET` request performs a `READ` operation. This is the default request method.
POST	Create	This request is used to create a new resource on a server. If you perform a `POST` request, the server creates a new entry in the database and tells you whether the creation is successful. In other words, a `POST` request performs an `CREATE` operation.
PUT	Update	This request is used to update a resource on a server. If you perform a `PUT`request, the server updates an entry in the database and tells you whether the update is successful. In other words, a `PUT` or performs an `UPDATE` operation.
DELETE	Delete	This request is used to delete a resource from a server. If you perform a `DELETE` request, the server deletes an entry in the database and tells you whether the deletion is successful. In other words, a `DELETE` request performs a `DELETE` operation.

Authentication

Our API provides OAuth 2.0 as a protocol for authenticating and authorizing PeerAssist users.

When using OAuth, a PeerAssist user will be required to log into their PeerAssist account and authorize your application access to their data.

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization.
.
Using our Authentication Controller you will be able to login to the API and receive an access token.

These tokens expire after 60 minutes so it is important to retrieve a new access token periodically when you are using the API.

Submitting this example cURL will return an access token based on the API key, username and password supplied.

curl -X POST "//api.mypeerassist.com/auth?clientKey=xyz" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"password\": \"password123\", \"userName\": \"[email protected]\"}"

The response from this will look as follows:

{
  "token": "string",
  "tokenType": "Bearer",
  "expiresIn": 60
}

The token returned by the auth service is the one that needs to be added to every service call to retrieve/push data.

The token is added to the headers in the following way:
Header:
Authorization: Bearer Yn2kjibddFAWtnPJ2AFlL8WXmohJMCvigQggaEypa5A

Every single http request must be signed with this header in order to be able to communicate with the API.

Requests

API requests can be built using our API reference guide.

This is an example of a GET request for Customer Details using cURL. Each request is defined along with the parameters that are passed so that you can try it out and view the string it produces.

Passing the parameter of 3 in this case for a specific customer is part of the URL.

curl --request GET \
  --url https://api.mypeerassist.com/customer/3 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer  Access Token

Additional parameters for a POST or PUT request can be added to the body of the request.

Here is an example of a POST customer ( Create Customer ) request using cURL that contains the new customer details as part of the body of the request.

curl --request POST \
  --url https://api.mypeerassist.com/customer \
  --header 'accept: */*' \
  --header 'authorization: Bearer access_token' \
  --header 'content-type: application/json'
  
  curl -X POST "http://45.55.190.178:9090/customer" -H "accept: */*" -H "Authorization: Bearer Access Token -H "Content-Type: application/json" -d "{ \"address1\": \"1234 Test Address\", \"address2\": \"\", \"billingContact\": \"Test Contact\", \"billingContactEmail\": \"[email protected]\", \"billingContactPhone\": \"0000000000\", \"billingTemplateId\": 0, \"city\": \"\", \"contactEmail\": \"[email protected]\", \"contactName\": \"Test Contact\", \"contactPhone\": \"0000000000\", \"id\": 0, \"name\": \"Test New Customer\", \"number\": \"01000\", \"state\": \"OH\", \"status\": \"ACTIVE\", \"tradeTemplateId\": 0, \"updateFWOs\": false, \"updateProjects\": false, \"zipCode\": \"\"}"

Responses

The response from a request will be returned in a JSON string. This is an example of a response from a Retrieve Customer Details function call.

{
  "id": 3,
  "name": "USA General Contractors, Inc.",
  "number": "200-000",
  "address1": "123 America Street",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94104",
  "contactName": "Test Contact",
  "contactEmail": "[email protected]",
  "billingContact": "Test Contact",
  "billingContactEmail": "[email protected]",
  "billingContactPhone": "0000000000",
  "contactPhone": "6144561447",
  "status": "ACTIVE"
}

Here is the response from creating a new customer with a HTTP status code of 200

{
  "id": 4,
  "name": "Test New Customer",
  "number": "01000",
  "address1": "1234 Test Address",
  "address2": "",
  "city": "",
  "state": "OH",
  "zipCode": "",
  "contactName": "Test Contact",
  "contactEmail": "[email protected]",
  "billingContact": "Test Contact",
  "billingContactEmail": "[email protected]",
  "billingContactPhone": "0000000000",
  "contactPhone": "0000000000",
  "status": "ACTIVE"
}

HTTP Status Codes

The HTTP status codes that are utilized in this API are described below.

HTTP CODE	RETURN WORD	DESCRIPTION
200	OK	It indicates that the REST API successfully carried out whatever action the client requested.
201	CREATED	A REST API responds with the 201 status code whenever a resource is created inside a collection.
204	NO CONTENT	The 204 status code is usually sent out in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the response message’s body.
401	UNAUTHORIZED	A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It usually means your API key is incorrect or invalid.
403	FORBIDDEN	A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it i.e. the user does not have the necessary permissions for the resource.
404	NOT FOUND	The 404 error status code indicates that the REST API can’t map the client’s URL to a resource but may be available in the future. It means that the URL is invalid or the ID of the object in the request is invalid.

Pagination

Many times, when a request is made, it will return a lot of results that can in turn affect the response times for your application. In order to help make this easier to manage, we paginate the results.

For example, you may request a list of all the Field Work Items ever created and that may return thousands of items which may be a difficult place to start.

Pagination limits the results to pages and number of results per page so you can specify how many items are returned per page and how many total pages to return.

In our FWO controller object the GET /fwo (Retrieve FWOs with pagination's) is an example of this use of pagination.

Try it out

Go to our API reference, review all the functions that are available and try it out.

Using the examples as a guide, you will be well on your way to accessing and updating your PeerAssist data.

If you have any questions, additional API requests or issues please do not hesitate to get in touch by emailing [email protected]