NAV

REST API Overview

Technically Write IT (TWi) Ltd. provides an example service to demonstrate a real-world REST API in action. Clients can send HTTP requests to service endpoints and receive responses. This document describes the Application Programming Interface (API) that enables client-side application developers to communicate with the service.

Using the API, developers can perform Create, Read, Update, and Delete (CRUD) operations on database objects using the following REST API requests:

This document describes the details of the requests that can be issued, including:

Application Database

To demonstrate REST API capabilities we are using the sample database that comes with SQLite. SQLite is a software library that provides a relational database management system and is popular for developing small-scale applications.

SQLite Tutorial Database Entity-Relationship (ER) Diagram

Getting Started

Getting started couldn’t be simpler! To get information about all the customers registerd in the database, in your favorite browser enter the URL shown in the panel on the right:

https://twiapi.herokuapp.com/api/customers

You get a response in JavaScript Object Notation (JSON) format showing the details of each customer in the database.

Similarly, to get information about all the employees in the database, in the browser, enter the URL shown in the panel on the right:

https://twiapi.herokuapp.com/api/employees

You get a response in JSON format showing the details of each employee in the database.

In a browser URL, it is only possible to issue GET requests. To issue more complicated REST requests, you can use a tool called Postman.

Postman

Postman is an online platform that allows API developers to collaborate on the development of REST API applications. The part we are most interested in is the Postman API Client.

We can use this client to send all types of requests to our REST API (or any REST API) and view the responses, status codes, and error messages. It is the ideal tool for REST API testing.

The Postman API Client is freely available from it download page.

The Postman API Client user interface is quite intuitive, but to help you get started, check out Postman’s own documentation.

Managing Information in the Database

You can use the TWi REST API for:

Customer Management

You can view and edit the information retained in the database for customers. This information includes:

The Customer ID is generated automatically by the database, and it cannot be changed. Attempting to do so results in an error.

The First Name, Last Name, and Email are required fields, so you must specify them when adding a new customer. If you do not specify these fields when adding a customer, you receive an error.

The Support Representative ID is the ID of an employee that is assigned to the customer.

Using the TWi REST API, you can:

Employee Management

You can view and edit the information retained in the database for employees. This information includes:

The Employee ID is generated automatically by the database, and it cannot be changed. Attempting to do so results in an error.

The First Name, Last Name, and Email are required fields, so you must specify them when adding a new employee. If you do not specify these fields when adding an employee, you receive an error.

The Reports To parameter is the ID of an employee that the employee reports to.

Using the TWi REST API, you can:

Customers

View Details of All Customers

You can get a list of all customers with details by sending an HTTP GET request to the /api/customers endpoint.

Request POST /api/customers
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the get customer details request is successful, the service returns a response.

The body of the response contains a JSON structure as follows:

[
    {
        "CustomerId": 1,
        "FirstName": "Luis",
        "LastName": "Goncalves",
        "Company": "Embraer - Empresa Brasileira de Aeronautica S.A.",
        "Address": "Av. Brigadeiro Faria Lima, 2170",
        "City": "Sao Jose dos Campos",
        "State": "SP",
        "Country": "Brazil",
        "PostalCode": "12227-000",
        "Phone": "+55 (12) 3923-5555",
        "Fax": "+55 (12) 3923-5566",
        "Email": "luisg@embraer.com.br",
        "SupportRepId": 3
    },
    {
        "CustomerId": 2,
        "FirstName": "Leonie",
        "LastName": "Kohler",
        "Company": null,
        "Address": "Theodor-Heuss-Strasse 34",
        "City": "Stuttgart",
        "State": null,
        "Country": "Germany",
        "PostalCode": "70174",
        "Phone": "+49 0711 2842222",
        "Fax": null,
        "Email": "leonekohler@surfeu.de",
        "SupportRepId": 5
    },
    ...
]

The response contains a list of the details for each customer. The customer details include the following parameters:

Field Description Type
CustomerId The internal unique ID of the customer, for example 7. Integer
FirstName The first name of the customer. Varchar
LastName The last name of the customer. Varchar
Company The name of the customers company. Varchar
Address The address of the customer. Varchar
City The city in which the customer is based. Varchar
State The state in which the customer is based. Varchar
Country The country in which the customer is based. Varchar
PostalCode The postal code of the customer’s location. Varchar
Phone The customer’s phone number. Varchar
Fax The customer’s FAX number. Varchar
Email The customer’s email address. Varchar
SupportRepId The ID of the employee assigned to the customer. Integer

Errors

None.

View Details of a Single Customer

You can get details of a specific customer by sending an HTTP GET request to the /api/customers/<ID> endpoint, where <ID> is a placeholder for an actual employee ID.

Request POST /api/customers/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the get customer details request is successful, the service returns a response.

The body of the response contains a JSON structure similar to the following. The assumption is that the <ID> specified was 2.

[
    {
        "CustomerId": 2,
        "FirstName": "Leonie",
        "LastName": "Kohler",
        "Company": null,
        "Address": "Theodor-Heuss-Strasse 34",
        "City": "Stuttgart",
        "State": null,
        "Country": "Germany",
        "PostalCode": "70174",
        "Phone": "+49 0711 2842222",
        "Fax": null,
        "Email": "leonekohler@surfeu.de",
        "SupportRepId": 5
    }
]

The response contains a list of the details for the customer. The customer details include the following parameters:

Field Description Type
CustomerId The internal unique ID of the customer, in this case 2. Integer
FirstName The first name of the customer. Varchar
LastName The last name of the customer. Varchar
Company The name of the customers company. Varchar
Address The address of the customer. Varchar
City The city in which the customer is based. Varchar
State The state in which the customer is based. Varchar
Country The country in which the customer is based. Varchar
PostalCode The postal code of the customer’s location. Varchar
Phone The customer’s phone number. Varchar
Fax The customer’s FAX number. Varchar
Email The customer’s email address. Varchar
SupportRepId The ID of the employee assigned to the customer. Integer

Errors

None. If you specify an customer ID that does not exist, the response is null.

Add a New Customer

You add a new customer by sending an HTTP POST request with the required customer information to the /api/customers endpoint.

Note

The FirstName, LastName, and Email parameters are required and you must specify them in your request. You can optionally include other parameters in the request.

Request POST /api/customers
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

An example of the JSON structure in the request body is as follows:

{
    "FirstName": "Len",
    "LastName": "Baker",
    "Email": "len.baker@technicallywriteit.com"
}

The request body can include the following:

Input Parameter Description Type Size Mandatory Default Value
FirstName The first name of the customer. Varchar 2-40 Yes -
LastName The last name of the customer. Varchar 2-20 Yes -
Company The name of the customers company. Varchar 80 No -
Address The address of the customer. Varchar 70 No -
City The city in which the customer is based. Varchar 40 No -
State The state in which the customer is based. Varchar 40 No -
Country The country in which the customer is based. Varchar 40 No -
PostalCode The postal code of the customer’s location. Varchar 40 No -
Phone The customer’s phone number. Varchar 40 No -
Fax The customer’s FAX number. Varchar 40 No -
Email The customer’s email address. Varchar 40 Yes -
SupportRepId The ID of the employee assigned to the customer. Varchar 40 No -

Example Response

If the add customer request is successful and the service allocates a CustomerID, the service returns a response.

The response is as follows:

"The customer record was added."

Errors

If the add customer request is not successful, the service responds with an error code, rejects the request, and does not create the customer record in the database. Some examples of error messages are provided.

A parameter value is longer or shorter than the specified range. For example, if FirstName is shorter than two characters or longer than 40 characters, the following errors are generated:

"FirstName" length must be at least 2 characters long"

or

"FirstName" length must be less than or equal to 40 characters long"

If an email address is specified in an incorrect format:

"Email" must be a valid email"

Edit Customer Details

You can edit customer details by sending an HTTP PUT request with the relevant customer information to the /api/customers/<ID> endpoint, where <ID> is the ID of the customer.

Request PUT /api/customers/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

An example of the JSON structure in the request body is as follows:

{
    "City": "Cork",
    "Country": "Ireland",
    "Phone": "+353 (0) 21 2428800"
}

The request body can include the following:

Input Parameter Description Type Size Mandatory Default Value
FirstName The first name of the customer. Varchar 2-40 Yes -
LastName The last name of the customer. Varchar 2-20 Yes -
Company The name of the customers company. Varchar 80 No -
Address The address of the customer. Varchar 70 No -
City The city in which the customer is based. Varchar 40 No -
State The state in which the customer is based. Varchar 40 No -
Country The country in which the customer is based. Varchar 40 No -
PostalCode The postal code of the customer’s location. Varchar 40 No -
Phone The customer’s phone number. Varchar 40 No -
Fax The customer’s FAX number. Varchar 40 No -
Email The customer’s email address. Varchar 40 Yes -
SupportRepId The ID of the employee assigned to the customer. Varchar 40 No -

Example Response

If the edit customer details request is successful, the service returns a response.

The response is as follows:

"The customer record was updated."

Errors

If the edit customer details request is not successful, the service responds with an error code, rejects the request, and does not update the customer record in the database. Some examples of error messages are provided.

A parameter value is longer or shorter than the specified range. For example, if City is shorter than two characters or longer than 40 characters, the following errors are generated:

"City" length must be at least 2 characters long"

or

"City" length must be less than or equal to 40 characters long"

If an email address is specified in an incorrect format:

"Email" must be a valid email"

Delete a Customer

You delete a customer record by sending an HTTP DELETE request to the /api/customers/<id> endpoint, where <ID> is the ID of the customer record to be deleted.

Request DELETE /api/customers/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the delete customer request is successful, the service returns a response with a message.

"The customer record is deleted."

Employees

View Details of All Employees

You can get a list of all employees with details by sending an HTTP GET request to the /api/employees endpoint.

Request POST /api/employees
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the get employee details request is successful, the service returns a response.

The body of the response contains a JSON structure as follows:

[
    {
        "EmployeeId": 1,
        "LastName": "Adams",
        "FirstName": "Andrew",
        "Title": "General Manager",
        "ReportsTo": null,
        "BirthDate": "1962-02-18 00:00:00",
        "HireDate": "2002-08-14 00:00:00",
        "Address": "11120 Jasper Ave NW",
        "City": "Edmonton",
        "State": "AB",
        "Country": "Canada",
        "PostalCode": "T5K 2N1",
        "Phone": "+1 (780) 428-9482",
        "Fax": "+1 (780) 428-3457",
        "Email": "andrew@chinookcorp.com"
    },
    {
        "EmployeeId": 2,
        "LastName": "Edwards",
        "FirstName": "Nancy",
        "Title": "Sales Manager",
        "ReportsTo": 1,
        "BirthDate": "1958-12-08 00:00:00",
        "HireDate": "2002-05-01 00:00:00",
        "Address": "825 8 Ave SW",
        "City": "Calgary",
        "State": "AB",
        "Country": "Canada",
        "PostalCode": "T2P 2T3",
        "Phone": "+1 (403) 262-3443",
        "Fax": "+1 (403) 262-3322",
        "Email": "nancy@chinookcorp.com"
    },
    ...
]

The response contains a list of the details for each employee. The employee details include the following parameters:

Field Description Type
EmployeeId The internal unique ID of the employee, for example 7. Integer
FirstName The first name of the employee. Varchar
LastName The last name of the empoloyee. Varchar
Title The role of the employee in the company, for example, “General Manager”. Varchar
ReportsTo The ID of the person (employee) to which the employee reports. Integer
BirthDate The employee’s birth date. Varchar
HireDate The date on which the employee started with the company. Varchar
Address The address of the employee. Varchar
City The city in which the employee is based. Varchar
State The state in which the empoloyee is based. Varchar
Country The country in which the employee is based. Varchar
PostalCode The postal code of the employee’s location. Varchar
Phone The employee’s phone number. Varchar
Fax The empoloyee’s FAX number. Varchar
Email The empoloyee’s email address. Varchar

Errors

None.

View Details of a Single Employee

You can get details of a specific employee by sending an HTTP GET request to the /api/customers/<ID> endpoint, where <ID> is a placeholder for an actual employee ID.

Request POST /api/employees/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the get employee details request is successful, the service returns a response.

The body of the response contains a JSON structure similar to the following. In this case, the assumption is that the <ID> specified is 2.

[
    {
        "EmployeeId": 2,
        "LastName": "Edwards",
        "FirstName": "Nancy",
        "Title": "Sales Manager",
        "ReportsTo": 1,
        "BirthDate": "1958-12-08 00:00:00",
        "HireDate": "2002-05-01 00:00:00",
        "Address": "825 8 Ave SW",
        "City": "Calgary",
        "State": "AB",
        "Country": "Canada",
        "PostalCode": "T2P 2T3",
        "Phone": "+1 (403) 262-3443",
        "Fax": "+1 (403) 262-3322",
        "Email": "nancy@chinookcorp.com"
    }
]

The response contains the details of the employee which include the following parameters:

Field Description Type
EmployeeId The internal unique ID of the employee. Integer
FirstName The first name of the employee. Varchar
LastName The last name of the employee. Varchar
Title The role of the employee in the company, for example, “General Manager”. Varchar
ReportsTo The ID of the person (employee) to which the employee reports. Integer
BirthDate The employee’s birth date. Varchar
HireDate The date on which the employee started with the company. Varchar
Address The address of the employee. Varchar
City The city in which the employee is based. Varchar
State The state in which the empoloyee is based. Varchar
Country The country in which the employee is based. Varchar
PostalCode The postal code of the employee’s location. Varchar
Phone The employee’s phone number. Varchar
Fax The empoloyee’s FAX number. Varchar
Email The empoloyee’s email address. Varchar

Errors

None. If you specify an employee ID that does not exist, the response is null.

Add an Employee

You add a new employee by sending an HTTP POST request with the required employee information to the /api/employees endpoint.

Note

The FirstName, LastName, and Email parameters are required and you must specify them in your request. You can optionally include other parameters in the request.

Request POST /api/employees
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

An example of the JSON structure in the request body is as follows:

{
    "FirstName": "John",
    "LastName": "Flannery",
    "Email": "john.flannery@technicallywriteit.com"
}

The request body can include the following:

Input Parameter Description Type Size Mandatory Default Value
FirstName The first name of the employee. Varchar 2-40 Yes -
LastName The last name of the employee. Varchar 2-20 Yes -
Title The role of the employee in the company, for example, “General Manager”. Varchar 30 No -
ReportsTo The ID of the person (employee) to which the employee reports. Integer - Yes -
BirthDate The employee’s birth date. Datetime - Yes -
HireDate The date on which the employee started with the company. Datetime - Yes -
Address The address of the employee. Varchar 70 No -
City The city in which the employee is based. Varchar 40 No -
State The state in which the empoloyee is based. Varchar 40 No -
Country The country in which the employee is based. Varchar 40 No -
PostalCode The postal code of the employee’s location. Varchar 40 No -
Phone The employee’s phone number. Varchar 40 No -
Fax The empoloyee’s FAX number. Varchar 40 No -
Email The empoloyee’s email address. Varchar 40 Yes -

Example Response

If the add employee request is successful and the service allocates an EmployeeID, the service returns a response.

The response is as follows:

"The employee record was added."

Errors

If the add employee request is not successful, the service responds with an error code, rejects the request, and does not create the employee record in the database. Some examples of error messages are provided.

A parameter value is longer or shorter than the specified range. For example, if FirstName is shorter than two characters or longer than 40 characters, the following errors are generated:

"FirstName" length must be at least 2 characters long"

or

""FirstName" length must be less than or equal to 40 characters long"

If an email address is specified in an incorrect format:

"Email" must be a valid email"

Edit Employee Details

You can edit employee details by sending an HTTP PUT request with the relevant employee information to the /api/employees/<ID> endpoint, where <ID> is the ID of the employee.

Request PUT /api/customers/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

An example of the JSON structure in the request body is as follows:

{
    "City": "Galway",
    "Country": "Ireland"
}

The request body can include the following:

Input Parameter Description Type Size Mandatory Default Value
FirstName The first name of the employee. Varchar 2-40 Yes -
LastName The last name of the employee. Varchar 2-20 Yes -
Title The role of the employee in the company, for example, “General Manager”. Varchar 30 No -
ReportsTo The ID of the person (employee) to which the employee reports. Integer - Yes -
BirthDate The employee’s birth date. Datetime - Yes -
HireDate The date on which the employee started with the company. Datetime - Yes -
Address The address of the employee. Varchar 70 No -
City The city in which the employee is based. Varchar 40 No -
State The state in which the empoloyee is based. Varchar 40 No -
Country The country in which the employee is based. Varchar 40 No -
PostalCode The postal code of the employee’s location. Varchar 40 No -
Phone The employee’s phone number. Varchar 40 No -
Fax The empoloyee’s FAX number. Varchar 40 No -
Email The empoloyee’s email address. Varchar 40 Yes -

Example Response

If the edit employee details request is successful, the service returns a response.

The response is as follows:

"The customer record was updated."

Errors

If the add customer request is not successful, the service responds with an error code, rejects the request, and does not update the customer record in the database. Some examples of error messages are provided.

A parameter value is longer or shorter than the specified range. For example, if Country is shorter than two characters or longer than 40 characters, the following errors are generated:

"Country" length must be at least 2 characters long"

or

"Country" length must be less than or equal to 40 characters long"

Delete an Employee

You delete an employee record by sending an HTTP DELETE request to the /api/employees/<id> endpoint, where <ID> is the ID of the employee record to be deleted.

Request DELETE /api/employees/<ID>
Host https://twiapi.herokuapp.com
Content Type application/json
Headers -

Request Body Payload Example

None.

Example Response

If the delete employee request is successful, the service returns a response with a message.

"The employee record is deleted."