Create a New Record

APIs - Creating New Records (POST)

RegScale APIs are often used to create or update records in the platform to support third party integrations or to support bulk processing. Example use cases are shown below:

• Pulling data from a 3rd party system and creating/updating records in RegScale
• Bulk loading existing data into RegScale to avoid manual data entry

This page is intended to help you understand how the APIs work in RegScale for creating new records and includes example code to get you started.

Understanding Data Structures

The first step to creating records with APIs is to understand the data structure of the object you are trying to create. To view the data structure, click your name in the top right of RegScale, select "APIs", and then RegScale will redirect you to the Swagger endpoint that contains our RegScale API definitions. An example is shown below for the catalogue object:

This screenshot shows the specific fields and data types that should be passed to the API to create a new record. In addition, once you have authorized the page with your bearer token (JWT), you can try out the API directly in the web page for testing.

Special Fields

For most RegScale objects, there are special fields that cannot be explicitly set. These include:

• "id" - this is usually an auto-number field that serves as a primary key within this RegScale instance. The recommended value to send in the JSON is 0
• "uuid" - this is automatically set as a globally unique identifier when moving records between different RegScale instances. The recommended value to send in the JSON is an empty string ''

In general, if these fields are manually set in the JSON, they will be ignored and over-written on the server-side.

Example Python Code

The code below shows how to create a new object using the API in RegScale after having authenticated in a previous step where the bearer token (JWT) and user ID have been established. The code example is provided in Python:

# create header with JWT token after authenticating
response = requests.request("POST", url_login, json=auth)
authResponse = response.json()
userId = authResponse["id"]
jwt = "Bearer " + authResponse["auth_token"]
headers = {
   'Authorization': jwt
}

# set the catalogue URL for your RegScale instance
url_cats = "https://sandbox.regscale.com/api/catalogues"

# setup catalog data
cat = {
    "title": "NIST 800-53 Rev. 4 - Security and Privacy Controls for Information Systems and Organizations",
    "description": "This publication provides a catalogue of security and privacy controls for information systems and organizations to protect organizational operations and assets, individuals, other organizations, and the Nation from a diverse set of threats and risks, including hostile attacks, human errors, natural disasters, structural failures, foreign intelligence entities, and privacy risks. <br/><br/><strong>Resources</strong><br/><br/>" + strResources,
    "datePublished": "1/22/2015",
    "lastRevisionDate": "1/22/2015",
    "url": "https://csrc.nist.gov/publications/detail/sp/800-53/rev-4/final",
    "abstract": "This publication provides a catalogue of security and privacy controls for federal information systems and organizations and a process for selecting controls to protect organizational operations (including mission, functions, image, and reputation), organizational assets, individuals, other organizations, and the Nation from a diverse set of threats including hostile cyber attacks, natural disasters, structural failures, and human errors (both intentional and unintentional). The security and privacy controls are customizable and implemented as part of an organization-wide process that manages information security and privacy risk. The controls address a diverse set of security and privacy requirements across the federal government and critical infrastructure, derived from legislation, Executive Orders, policies, directives, regulations, standards, and/or mission/business needs. The publication also describes how to develop specialized sets of controls, or overlays, tailored for specific types of missions/business functions, technologies, or environments of operation. Finally, the catalogue of security controls addresses security from both a functionality perspective (the strength of security functions and mechanisms provided) and an assurance perspective (the measures of confidence in the implemented security capability). Addressing both security functionality and assurance helps to ensure that information technology component products and the information systems built from those products using sound system and security engineering principles are sufficiently trustworthy.",
    "keywords": "FIPS Publication 200; FISMA; Privacy Act; Risk Management Framework; security controls; FIPS Publication 199; security requirements; computer security; assurance;",
    "createdById": userId,
    "lastUpdatedById": userId }

# create the catalog and print success result
response = requests.request("POST", url_cats, headers=headers, json=cat)
jsonResponse = response.json()
print("RegScale Output")
print("Catalog ID: " + str(jsonResponse["id"]))

The workflow for this code is described below:

• Initial call logs into RegScale and provides a token (JWT) that is added to the header. It also provides the user information for the logged in user.
• Header is created to append to all API requests to authenticate to the API services.
• URL is established for the "POST" endpoint
• New catalog is created using the fields specified in the API definition for this object
• New POST request is made to the provided URL, with the provided header, with this object attached as a JSON file in the body
• Response prints the ID of the newly created record in RegScale

This same process can be used for any object in RegScale as they all have well-defined CREATE, READ, UPDATE, and DELETE APIs. The only difference is the object name and fields specific to that API call.

NOTE: The user must have permissions to create records for that module in order for the API calls to work.