API Details
Selecting the API Details from the Catalog allows you to view additional developer information.
On This Page
API Detail Items
- Actions: Located at the top right of each API Details page, includes:
- Generate OAuth: Open Authorization "OAuth" is a set of credentials that generate a session token.
- Related Documents: API Guides, Release Documents, Error Code Messages, additional testing documentation and technical documentation.
- Overview: Typically a use case for the API, a summary of what the API does and foundational API information.
- Download API Specifications: The full API specifications file.
- Production URL: API endpoint URL(s) for the production environment which will be used when the API integration is ready to go live.
- API Version: As APIs evolve, new versions are made available. Older versions can be accessed from a drop-down menu.
- SDK: Abbreviation for “Software Development Kits.” SDK are downloadable, pre-developed, code translation tools for common languages like .NET or Java – Freddie Mac SDKs include a README file to identify dependencies, instructions, additional help, and details for developers. SDKs are only available for the latest version of an API.
- Server Endpoints: A drop-down menu containing the web address of each api-test server.
Navigating through an API's Open Documentation Specification Details
If you have not built an App and associated the desired API, you will need an App for your credentials before you complete these steps. Visit the Topic My Apps and see the section titled process to learn more.
If you have already built an App, and associated it to your API, proceed with the steps below.
- Open the API Catalog from the page header.
- Scroll down the API Catalog and select the API Details link from the API card.
- Generate a token. Click the Key action icon
.
Note: Pricing and Committing APIs do not require building an App. Clicking the Key "action" icon will not be available if the API is a draft version and not yet available for testing.
- Generate OAuth by filling out the form below and click GENERATE. Having already made an App, you can select the desired App from the drop-down (steps 1 and 2 below). Doing this will conveniently and accurately auto-fill the Client ID and Client Secret fields.
To switch Apps, click CLEAR POPULATED DATA to reset the form.
Note: Company Username: the Freddie Mac API Product-specific System-to-System user name that Freddie Mac issued to your organization to access the desired API, e.g., testorg_API2Sys2SysCTECompany Password: the System-to-System password that Freddie Mac issued to your organization with your System-to-System user name.
- Your Token will be generated. Copy your token to the clipboard.
- Click Authorize.
- Activate your available authorization. Most Freddie Mac APIs use OAuth, but the Pricing and Committing APIs use Basic Auth.
OAuth Version
Enter or paste the generated token into the value field for the "Bearer" token. Click Authorize.
Click Close to proceed.
Basic Auth Version (Pricing and Committing APIs only)
Enter Username and Password.
- Username: Company System ID that Freddie Mac issued to your organization to access the desired API, e.g., testorg_API2Sys2SysCTE
- Password: System Password that Freddie Mac issued to your organization
Click Authorize.
Click Close to proceed.
- Click on the method (in the example below "Post") to expand the green drop-down.
- Click Try It Out and choose a scenario from the drop-down. Use pre-filled values as guidance to get a sense for what values should be entered for each request field.
Note: Every API has at least two or more example scenarios for you to choose from and execute. Sample scenarios are available in the drop down Examples field and cover major scenarios for the API. Some APIs will have additional sample test files available in the APIs Related Documentation page.
- Click Execute.
- Scroll down the page to see the fully executed response from the API.
Note: You can execute as many test scenarios from the Examples drop down as you would like and make adjustments to your values within the request box to deepen your understanding of how the API works.
View API Messages
For APIs, responses are listed to allow you to view messages. There are several ways to locate these responses for an API. (See numbers on image below and corresponding descriptions following)
- Method tabs On the API Swagger Page: Locate responses by selecting a Method to expand the tab. Scroll down to see all the responses for an API.
Note:
In the 200 Section you will see a list of the Successful messages you can receive when calling the API.
In the 400 section you will see the potential 400 Error Messages you can receive when there is something wrong with your Request.
In the 500 section you will see the potential 500 Error Messages you can receive when there is something wrong with the system.
- Related Documents: For some APIs that have a larger number of messages returned through the API, there may be additional documentation available in Related documents. There you can find a complete list of the potential messages that the API can return, in addition to the messages available when viewing the API in the Swagger UI.
- Download the Specification File: Locate responses by selecting the download button to download the specification file.
Example Values and Schema
Example Values: In this format you will see the structured request or response with detailed transactional identifiers.
Schema: In this format you will see schema details and be able to "drill down" to learn more about each data field including a detailed description of the field, indication of required or optional, type of data field, valid values for the field by using the expand arrows and dots controls available to you.
