External API's Glossary

2 Minute Read

| Glossary

Project Haystack: https://project-haystack.org/ 

Site Explorer Tool: Tool within 75F that can be accessed by API Developers who have been authorized for a few sites and their data. 

REST: A software architectural style that defines a set of constraints to be used for creating web services. When HTTP is used, the operations (HTTP methods) available are GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, OPTIONS and TRACE.  

JSON Notation 

JSON notation is used for the serialization of request/response objects sent to and from the 75F API. JSON is a lightweight data-interchange format. It is easy for humans to read and write and machines to parse and generate. JSON is the most common, open format, used widely in all manner of web-based applications. There are JSON parsers available for almost all development languages. 

For more information on JSON refer at http://json.org 

| API Startup Section 

Authentication 

• Consumers must first authenticate before gaining access to any of our APIs.   
• OpenAPI 3.0 allows us to describe the following mechanisms:  
  • HTTP authentication schemes (they use the Authorization header):  
  • Basic  
  • Bearer  
  • API keys in headers, query strings, or cookies  
  • Cookie authentication  
  • OAuth 2  
  • OpenID Connect Discovery  

75F supports the bearer auth mechanism and it is accurately documented in the Developer portal. 

Requests 

Requests must have a clearly defined schema, sample body, and parameters if available.   

At a glance, a user must be able to extract the following information:  

• The purpose of the endpoint – what is the business value provided to a user?    
• HTTP method:  
• Content-type (JSON, XML, etc.)  
• The authentication mechanism of the endpoint  
• Request schema  
• What an example of a request body would look like  
• URL query parameters (if applicable).  

Responses and Status Codes 

All responses for an endpoint must be documented along with example responses, response types (JSON, XML), and status codes.  

An API consumer should be able to easily understand what is expected when the endpoint is accessed.  

Error messages inform consumers of incorrect/broken API integrations, so it is good practice to indicate all possible error codes that consumers may receive.  

The following aspects must be clearly described:  

• Example response bodies and their schema (fields, data type, size, etc.)  
• Responses with meaningful status codes for all possible outcomes will provide context to API usage:  
• The client made a bad request such as forgetting to authenticate, sending an invalid request, etc.: 4xx  
• An internal server error occurred: 5xx  
• Successful response: 2xx