Contents

HTTP Fundamentals

This section provides a quick overview of HTTP concepts for PeopleSoft developers who may not work with HTTP and REST APIs daily. If you are already comfortable with HTTP requests, responses, status codes, and headers, feel free to skip ahead. This is meant as a level-set before diving into Integration Broker specifics.

What is HTTP?

HTTP (HyperText Transfer Protocol) is a text-based request and response protocol between clients and servers.

  • The client initiates all communication by sending an HTTP request.
  • The server processes the request and sends back an HTTP response.
  • HTTP is stateless – each request is independent.

In the PeopleSoft world:

  • When PeopleSoft is the server (inbound), it receives requests through listening connectors (RESTListeningConnector, HttpListeningConnector, etc.)
  • When PeopleSoft is the client (outbound), it sends requests through the HttpTargetConnector.

The HTTP Request

An HTTP request has four main parts:

Method (Verb)

The HTTP method tells the server what action you want to perform.

Method Purpose Has Body? Common Usage
GET Retrieve data No ~85% of API calls
POST Create a resource or send data Yes ~10% of API calls
PUT Replace/update a resource Yes Less common
PATCH Partially update a resource Yes Less common
DELETE Remove a resource No Less common

GET and POST account for the vast majority of PeopleSoft integration work. You will seldom use PUT and PATCH.

URL (Uniform Resource Locator)

A URL identifies the resource you are interacting with. Here is the anatomy of a URL:

https://api.example.com:443/v2/employees?status=active&limit=10
\___/   \______________/\__/\___________/ \____________________/
scheme       host       port    path         query string
  • Scheme: http or https (always use https for APIs)
  • Host: The server’s domain name
  • Port: 443 is the default for HTTPS, 80 for HTTP (usually omitted)
  • Path: Identifies the specific resource. In REST APIs, this often includes IDs like /employees/12345
  • Query String: Key-value pairs for filtering, pagination, etc. Starts with ? and uses & to separate pairs

Headers

Headers pass metadata about the request. Think of them as configuration for the HTTP transaction.

Common request headers you will encounter:

Header Purpose Example
Content-Type Format of the request body application/json, application/xml
Accept Format you want the response in application/json
Authorization Authentication credentials Basic dXNlcjpwYXNz, Bearer <token>

Body

The request body carries data you are sending to the server. Only POST, PUT, and PATCH requests typically have a body. The body can be JSON, XML, form data, or other formats.

Putting It Together – Example Requests

GET Request (No Body)

GET https://api.example.com/employees/12345
Accept: application/json
Authorization: Basic dXNlcjpwYXNz

There is no body. The URL path (/employees/12345) identifies which employee to retrieve.

POST Request (With JSON Body)

POST https://api.example.com/employees
Content-Type: application/json
Accept: application/json
Authorization: Basic dXNlcjpwYXNz

{
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "department": "HR"
}

The body contains the data for the new employee being created.

DELETE Request (No Body)

DELETE https://api.example.com/employees/12345
Authorization: Basic dXNlcjpwYXNz

The HTTP Response

The server sends back a response with three parts:

Status Code

The status code tells you the outcome. They are grouped by family:

Range Category Meaning
2xx Success The request worked
3xx Redirect The resource moved
4xx Client Error Something is wrong with your request
5xx Server Error The server had a problem

Common status codes you will encounter in PeopleSoft integrations:

Code Name What It Means
200 OK Request succeeded, response body has data
201 Created Resource was created (common response to POST)
204 No Content Success, but no response body (common for DELETE)
400 Bad Request Your request is malformed or has invalid data
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Authenticated but not authorized for this resource
404 Not Found The resource does not exist (sometimes this is not an error, e.g., checking if a record exists)
405 Method Not Allowed The endpoint does not support the HTTP method you used
408 Request Timeout The server timed out waiting; can sometimes be retried
429 Too Many Requests Rate limit exceeded; wait and retry
500 Internal Server Error The server crashed or had an unhandled error

Response Headers

Response headers carry metadata about the response. Some useful ones:

Header Purpose
Content-Type Format of the response body
X-Rate-Limit-Remaining How many API calls you have left
X-Rate-Limit-Reset When your rate limit resets
X-Request-ID Unique ID for the request (useful for support tickets)
Location URL of a newly created resource (after a 201)

Response Body

The response body contains the data you requested. Most modern APIs return JSON, though some still use XML.

Example JSON response:

{
  "id": "12345",
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "department": "HR",
  "active": true
}

Authentication

Most APIs require authentication. The two most common patterns you will encounter with PeopleSoft integrations:

Basic Authentication

Basic Auth sends a username and password encoded in Base64:

  1. Combine username and password: snoopy:i-fly-planes
  2. Base64 encode it: c25vb3B5OmktZmx5LXBsYW5lcw==
  3. Send in the Authorization header: Authorization: Basic c25vb3B5OmktZmx5LXBsYW5lcw==

Bearer Token (OAuth2)

Many modern APIs use token-based authentication:

  1. Make a separate request to get an access token (often with client credentials)
  2. Include the token in subsequent requests: Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
  3. Tokens expire – your code needs to handle token refresh

Data Formats

JSON

JSON (JavaScript Object Notation) is the dominant data format for modern APIs. It uses key-value pairs and is easy to read:

{
  "name": "Jane Smith",
  "age": 30,
  "active": true,
  "roles": ["admin", "user"],
  "address": {
    "city": "San Diego",
    "state": "CA"
  }
}

XML

XML is older and more verbose. You will still encounter it with some PeopleSoft integrations and SOAP services:

<?xml version="1.0"?>
<employee>
  <name>Jane Smith</name>
  <age>30</age>
  <active>true</active>
  <roles>
    <role>admin</role>
    <role>user</role>
  </roles>
</employee>

Real Infrastructure

In practice, HTTP requests between PeopleSoft and an external API go through several layers:

  1. PeopleSoft Application Server – Your PeopleCode runs here
  2. PeopleSoft Web Server / Integration Gateway – The HttpTargetConnector lives here and makes the actual outbound HTTP call
  3. Egress Firewall – Your organization’s outbound firewall
  4. External Firewall / API Gateway – The vendor’s ingress security (IP restrictions, SSL termination, rate limiting)
  5. API Server – The actual service endpoint

Each of these layers can introduce issues: DNS resolution, firewall rules, TLS certificate problems, and timeouts. See the HttpTargetConnector section for troubleshooting details.

Try It Yourself

The best way to learn HTTP is to make some requests. Here are some safe, public APIs you can test against using HTTPYac, curl, or Postman:

### Simple GET - returns your IP info as JSON
GET https://httpbin.org/get
Accept: application/json
### POST with JSON body - echoes back what you sent
POST https://httpbin.org/anything
Content-Type: application/json

{"message": "hello world"}
### Force a specific status code
GET https://httpbin.org/status/404
### Basic Auth test (user: user, password: passwd)
GET https://httpbin.org/basic-auth/user/passwd
Authorization: Basic dXNlcjpwYXNzd2Q=

These examples use httpbin.org, a free service that echoes back your requests. It is a great way to experiment with different HTTP methods, headers, and status codes without touching any real system.

Author Info
Chris Malek

Chris Malek s a PeopleTools® Technical Consultant with over two decades of experience working on PeopleSoft enterprise software projects. He is available for consulting engagements.

Work with Chris