Socket API Guidelines

Important: These guidelines are for internal use only. Please don't share them with anyone outside this organisation.

These guidelines are designed to help Temenos developers, business analysts and product specialists build Temenos APIs to the new Socket standards, and submit them to the Developer portal - developer.temenos.com - for publication. 

To help you create your API, we've also provided:

• The latest Socket vocabulary file.
• An example annotated .yaml.

To deliver your Temenos API to the portal, you'll need to:

1. Apply the principles outlined in these guidelines to your API.
2. Apply the Socket vocabulary file to your API.
3. Get sign off by the solution or project that commissioned it.
4. Provide an annotated .yaml for the specification as a pull request to the Socket Bitbucket repository. Annotations help the Socket team, and users, understand the design and flow of your API.

We may also ask you to provide the source content for a lifecycle guide, so that we can explain to site users the business context of your API. For more information about the submission process, see Submitting Your API.

What is Socket?

Our Socket standards were developed to make it easier for both developers and end-users to understand, use and extend our APIs and Events. And by rebuilding our APIs from the 'outside in' - by focusing on what the customer truly needs  - we're aiming to make our APIs more powerful too.

What's Wrong With Our Existing APIs?

Temenos APIs are powerful, and for the sheer range of banking functionality they cover, we can't be beaten. But we don't make it easy for our customers to apply and use our APIs, for a number of reasons:

• Many of our current APIs are built directly from Transact Enquiries and Versions. This can result in lots of duplicated and overlapping functionality, and low quality, poorly documented APIs.
• Our APIs are frequently too Transact-specific, which means that our users need an in-depth knowledge of the Transact solution to adapt and use the APIs. That makes it harder for our APIs to compete against cleaner, leaner API providers, working to leading industry standards.
• Our APIs are often structurally inconsistent. Because we've been working to local, rather than cross-company standards, we've introduced a bewildering range of inconsistencies into our APIs. For example, Boolean values are referenced as 0,1 in some places, and T,F, True, False, Y,N, or Yes, No in others.
• Users struggle, thanks to poor and inconsistent field descriptions . When we don't name, introduce or describe our APIs well, we make it a lot harder for users to understand and use our APIs.

If we apply Socket standards across our APIs from now on, we'll solve many of these issues, and reclaim our leadership in banking APIs.

Before You Start, Research

To make it as easy as possible for banks to consume our APIs, we need to follow international market standards, not Transact-specific standards. Before your project begins, check out the leading API specialists for inspiration and models of best practice.

Tip: To visit the API specialist, click the logo.

Good Examples From Temenos

Temenos is already building APIs to high, market-leading standards:

• For a fully documented API, designed for architects, see our Berlin Group PSD2 API. This API enables Open Banking through Temenos.
• For a sneak peak of Temenos retail banking APIs, built to Socket standards, see the Socket API Catalog on the Developer portal staging site.

How Granular?

It's a dilemma you often come across, when designing an API: do you create a complex API, that works for all use cases, or do you create many simpler ones, which inevitably means duplication?

Every business case is different, so it's your call. The prime directive of Socket is that APIs must be user friendly. Avoiding unnecessary complexity - layered interdependencies, where many fields are 'mandatory if field X > 20 and field Z is empty and it's a weekend' - is key to creating APIs that are both flexible and easy to use.

In some cases, it may be better to have more duplication and simpler APIs than a powerful but unwieldy all-purpose API. A balance has to be struck - but remember that comprehension is king.

Orchestrating and Combining APIs

We strongly recommend avoiding designs that force users to use multiple APIs to achieve a single business function. Doing it this way can be convenient for Temenos, where there's a great deal of Transact-specific knowledge, and there are situations where many Transact APIs have to be called to achieve a specific end. But our users will always expect a single API.

To meet Socket standards, and customer expectations, your API needs to hide the multiple operations required. If the API is using IRIS, then this means writing a Published API as opposed to a Provider API.

Analyse Your Business Case With The API Design Authority

The API Design Authority are there to help you analyse the business case, and required functionality, for your API. We strongly recommend getting their input before your project gets underway. For more information, contact either:

• Sangeetha Vasudevan
• Shivakumar Sampath

Put Your Specification On Confluence

It's not mandatory, but we recommend entering your API specification on Confluence. As the Socket team discovered, explaining the purpose and function of our APIs on Confluence, from both a technical and a banking viewpoint, helps you to create clearer, easier to understand APIs. We also used Confluence to document - and edit - the payloads and responses from APIs. 

For a good example of best practice, see the Card Management page on Confluence.

Socket Vocabulary File

The Socket standards project has developed a vocabulary file, to provide clear, consistent field definitions for Temenos APIs. The Socket vocabulary file is versioned through the Socket Bitbucket repository and published to developer.temenos.com/socket-vocabulary.

Recommendation: We strongly recommend using existing field definitions as far as possible. If you need to create new definitions, submit them to socket@temenos.com for review and signoff.

Overview and Fields

Remember, your API is a document. You'll need to write the overview to the API, and provide field names and descriptions, in simple, accurate English. Be informative, and get your overview and fields, including the value types, checked and signed off by project leadership. If you can, get a professional Temenos writer to check your English.

Overview

Introduce your API with a crystal clear business overview of what your API does - and sometimes doesn't - do.

Include:

• A brief, precise overview of the banking functionality your API enables. Explain how it relates to other APIs or banking solutions.
• Indicate where the API sits in the business workflow, for example, onboarding or account setup. Mention any business validation that needs to be performed - some fields may be mandatory, depending on the business logic.
• Use bullets to summarise what your API covers.
• Add Notes: to pass on extra information or tips to the user.

Recommendation: Business analysts should write the overview text, ideally. Use a grammar checking tool and get a colleague - or professional Temenos writer - to proof read what you've written.

Example Overviews

Field Names (Field Label)

Use the Socket two-part, camel-case format for field names. For example, sortCode. In rare cases, you can use a three-part, camel-case format, such as productLineName.

Avoid using single format field names, such as email or customer.

When selecting a field name, think about usage. For example, different banks have different value formats for customer identifiers, ranging from a simple numeric format (such as 900185) to formats that includes alphanumeric values (such as 876AE235RXS). In this instance, a good choice for the field name would be customerId, rather than custNo,, customerNumber, or custNumeric.

Example Field Names (Field Definitions)

 

• sortCode
• customerTitle
• accountNumber
• paymentReference
• productDescription
• productName

Field Descriptions

Good field descriptions help the user understand the business function of the field or endpoint. Write as simply and clearly as you can, and include examples, to show the user what you mean. Get a colleague or professional Temenos writer to check what you've written, and get your descriptions signed off by the project leadership.

Remember:

• Get to the point quickly. Avoid prepositions (A, The, An). If the field indicates an action, start your descriptions with a verb. For example:

  accountId

  Identifies the account. Often referred to as the account number

• Include examples, to make your description clearer. For example:

  cardTitle

  Title of the card product chosen by the customer. For example: AMEX Rewards Credit Card; CITI Super Saver Shopping Card; DBS Cashback Credit Card

• Neverend your final sentence with a full stop or period. For example:

  embossName	Customer name that’s embossed on the card. The default is the customer’s first and last name
  feeType	Type of fee that’s applicable to the customer’s chosen product

More Example Field Descriptions

creditAccountNumber	Number of the account to which the payment is made
creditAccountSortCode	Six-digit UK code that identifies the bank that holds the account to which the payment is made
transactionNarrative	Optional, free text description of the transaction by the payee
currencyCode	Currency code in ISO 4217 format. For example, USD, GBP
paymentType	Specifies the domestic payment system. For example, BACS, CHAPS or FPS

ENUMs and Reference Tables

If the field type is an ENUM, a list of dropdown options, then you need to specify the values clearly.

If the field retrieves its value from a reference API, then you'll need to provide the reference API name and describe how the values are retrieved.

Tip: For a good example of how to describe ENUM values, see the Socket confluence page on Card Management.

Example ENUMs

This ENUM example from a Temenos Socket API shows how to clearly document ENUM values.

This ENUM example from Finastra also shows best practice.

Reference Data Fields

Reference data fields retrieve data from coded lists, such as Sector and Customer Title. Describe to the user what values the list contains and where to retrieve the list.

Example Reference Data Fields

This example shows reference/lookup data for product types, when using GET to retrieve data from a reference data table.

Example Data

You'll need to populate your API with example data - representative values that truly show how your API works, not simply random letters, numbers or string values.

API Lifecycle Guide Content

We may ask you to provide content for an API lifecycle guide, to explain the API and the business workflow more fully to users. Usually, this source content is provided through your Confluence pages, when you specify your API.

Tip: For good examples of lifecycle guides, see Guides.

Submitting Your API

When you're ready to submit your API for publication to the Developer portal, contact socket@temenos.com. Provide the annotated .yaml for the specification as a pull request to the Socket Bitbucket repository. Annotations help us understand the design and flow of your API.

Give us as much notice as you can that you'll be delivering an API or APIs to us - this helps us schedule publication, and helps you to meet your project deadlines.

Important: We may come back to you with questions about your API. If we spot errors in your API, we'll ask you to correct these before we publish. You'll also need to inform us of any significant updates to your API, after first publication.

Next Steps

For more guidance, see:

• The latest Socket vocabulary file.
• Our example annotated .yaml.