# Simpson Strong-Tie API Guidelines

## 1. Preface

This document establishes the guidelines for Simpson Strong-Tie REST APIs, to ensure that interfaces are developed securely and consistently, and are made easy to use. Please see our [FAQs](/help-center/general/faqs) section for definitions of any terms.

## 2. Overview

### 2.1 Goals

The goals of these guidelines are:

* to provide application developers with resources to create and utilize RESTful HTTP interfaces
* to provide the smoothest possible experience for developers by providing consistent and intuitive design guidelines
* to establish a cohesive look and feel for all Simpson Strong-Tie web products and services
* to instill an "API-only" development approach where all communications between separate modules must happen via APIs


### 2.2 Non-Goals

The term "API" can mean a lot of things. In the context of this site, we're referring to service-level APIs that are exposed over the internet.

These guidelines do not cover programming languages or libraries used, server frameworks, or how an application might implement an API.

## 3. Guidelines

### 3.1 Security

We need to verify that the client is valid before using the Simpson Strong-Tie system.

### 3.2 Authentication and Authorization

#### 3.2.1 Authorization Grant

There are four grant types defined in the OAuth2 RFC 6749:

* Authorization Code
* Implicit
* Resource Owner Password Credentials
* Client Credentials


The Simpson Strong-Tie system currently supports only the "Client Credentials" type when acting as authorization server where the resource owner client credentials (i.e., "client_id" and "client_secret") can be used directly as an authorization grant to obtain an access token.

#### 3.2.2 Getting an access token from the Simpson Strongtie system

You can do this by the following POST request with multipart form-data in body:

> POST {baseURL}/oauth/token


| Parameter | Value |
|  --- | --- |
| grant_type | client_credentials |
| client_id | 12345 (unique id of the Client App configured) |
| client_secret | ABCDE (unique secret code of the Client App configured) |


JSON file that contains the access token and type of token will be returned:


```json
{
  "access_token": "eyJ4NXQjUzI1NiI6ImZYSkhReFpkTzlKWU1aaXFFaWQiO",
  "scope": "trust read write register",
  "allowed_services": "apigateway",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

### 3.3 Environments

* Staging Base URL: https://api-staging.strongtie.com/gws
* Production Base URL: https://api.strongtie.com/gws


### 3.4 Headers

All API endpoints expect request and response body data to be in JSON.
The following HTTP request headers may be required, depending on the operation and endpoint being invoked:

| Header | Definition | Example |
|  --- | --- | --- |
| **Authorization** | Required for all endpoints, except for POST /token. The access token. | https://api-staging.strongtie.com/gws/api/Hangers |
| **Content-Type** | Required for POST and PUT requests. Defines the structure for the response | https://api.strongtie.com/gws/api/Hangers |


### 3.5 HTTP Methods

HTTP has a defined set of methods.  These request methods are sometimes referred to as “HTTP verbs”. The common methods used by most RESTful web APIs are:

* POST
* PUT
* GET
* DELETE
* PATCH
* HEAD
* OPTIONS
* SAFE AND NON-SAFE METHODS


### 3.6 Status Codes

Simpson Strong-Tie uses a combination of HTTP status codes and custom error codes with a descriptive message in JSON-formatted Error objects to give you a more complete picture of what has happened with your request.