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 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:

{
  "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.