API Glossary and Frequently Asked Questions (FAQ)

Overview

This document contains a glossary with an alphabetical list, definitions, and of terms related to APIs/API Directory. Below the Glossary are some frequently asked questions (FAQ) with the applicable answers.

Glossary

  • Access Tokens provide the authorization necessary to allow client applications to call APIs that they are subscribed to.
  • APIs (Application Programming Interfaces) enable secure access to enterprise data assets and processes. They are usually in the form of REST or SOAP web services. APIs are the building blocks for app creation integrations.
  • Client Applications are the apps that developers build. When these applications call APIs from the API Directory, they are considered a client application of the API Directory.
  • Consumer Key and Secret are credentials associated with the client application. The Consumer Key and Secret are used to generate an Access Token, which is needed to make calls to APIs that the application is subscribed to.
  • cURLis a command line tool for transferring data in various protocols, in our case HTTP. Many of the API example calls are made in the cURL syntax. For more information about cURL, see the cURL website.
  • JSON (JavaScript Object Notation), much like XML is a way to transport and store data. JSON is smaller than XML and easier to parse.
  • REST (REpresentational State Transfer) is a stateless architecture that generally runs over HTTP. The REST style is resource based (nouns) which have their own unique URI, and operations on those resources are limited to HTTP verbs (GET, POST, PUT, and DELETE). For example, consider a resource called Account. You would do an HTTP GET to retrieve information about that Account, and an HTTP POST to update the Account. REST style APIs are considered by many easier to understand and consume, especially for mobile development. See Roy Fielding’s dissertation for more information on REST.
  • OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the web. There are two types of OAuth, 2-legged, which authenticates the client application, and 3-legged, which authenticates the client application and the end user. Currently, all of our APIs support 2-legged Oauth. 3-legged support will be coming soon.
  • SOAP stands for Simple Object Access Protocol. This method of web services transmits messages via XML, usually as an HTTP POST. SOAP services contain service operations that are requested by the calling application. These service operations usually contain verb/noun combinations (i.e. getAccountByID, getAccountByName, UpdateAccount…). One advantage to SOAP is that it provides WSDL (Web Service Definition Language) that describes the service operations. Most large enterprise applications support SOAP.
  • SoapUI is a free and open source graphical web service testing tool. It supports both SOAP and REST calls. Many of our API examples are documented in SoapUI. For more information about SoapUI, see the SoapUI website.
  • Throttling limits the number of requests an application can make to an API. Most of the APIs found in the API directory are limited to 60 calls per minute.
  • XML (Extensible Markup Language) is a way to transport and store data, with tags that say what the data is.
  • Properties Properties are name value pairs that can be used in the API functionality. API developers can define a different value for the same property in different environments like sandbox/test/production. The actual value will be used at runtime in the environment the client is consuming the API. Eg: endPointUrl is a property that can be used to define the actual API backend url that will be used in each environment at runtime.
  • Paths Paths are the resource urls the API developers choose to expose their API. Each path can have a GET/PUT/POST/DELETE http action defined. Paths can have defined parameters. The parameters can be specified as required/optional and as a Query / Path / header parameters as well. API developers can also specify the default values of the parameters.
  • Definitions Definitions are the syntax for the any properties you intend to use in the API development. API developer can define a property’s behavior in this section like if its an Array / Object with specific fields etc.
  • Tags Tags are metadata information about the API which will be very helpful when the API is published. Tags can be used for the consumers to search for the API. If the consumer searches by a tag that is defined within the API, the API will be displayed in the search results. We can have multiple tags defined for an API.

 

Frequently Asked Questions while Publishing an API Product

  • What are products? Products are the combination of the APIs and the plans. Products are the bundled artifacts that are published in the API Directory. They are staged and then Published in the API directory and provide a method by which you can group APIs into a package that is intended for a particular use. Additionally, they contain Plans, which can be used to differentiate between different offerings. Plans can share APIs, but whether subscription approval is required depends upon the Plan itself.
  • What are plans? A plan is collection of API resources or subsets of resources from one or more API. It can contain a mixture of HTTP GET, PUT, POST, and DELETE verbs from different APIs or it can contain all the GET verbs from various APIs. A plan can have a common rate limit for all the resources or each resource can have a different rate limit. Rate limits specify how many requests an application is allowed to make during a specified time interval.Use the API Directory to browse the different plans that are available to you and select a plan that is most suitable for your requirements. Some plans have restricted access that you must request access to use. When you submit your request, the data owner is notified, the API administrator assesses your request and they might contact you for more details. Other plans are available to use straight away
  • What does visibility mean? Visibility is the way you intend to display the API in API Directory.
  • Available options are:
    • Public: Viewable by anyone without logging in to the API Directory.
    • Authenticated Users:Must be logged in with UMICH credentials and be a part of the any developer org in the API Directory.
    • Custom: You must define your own groups (not recommended).
  • What does 'Subscribable by' mean? Subscribable defines who can subscribe to the plans/APIs. You can define a custom group of Developer Orgs that can subscribe or make it available to anyone who has authenticated using umich credentials and is part of any developer org.

Frequently Asked Questions while Consuming an API

  • How do I reset my application client secret? Your application client secret is stored encrypted so we cannot retrieve the unencrypted version to tell you the value if you forget it. You can reset it, which will update the stored value and return the new value to you. To do that click Apps in the main menu, click on the application in question and then you can click Reset link in the 'Client Secret' section.Your new secret will be displayed at the top of the page.
  • How do I see my API usage? The numbers of requests, for different APIs, that your application has made are shown on your application page. Click Apps in the main menu and then click on your application. Under 'Subscribed Plans' you will see all plans your application is subscribed to. For each API contained in that plan you can see the usage compared to the rate limit of the plan.
  • How can I test an API? It is possible to test an API from the API Directory. When looking at the details of an API you will see a table of the operations contained in the API. This will show what method they are (GET, POST, PUT, DELETE, PATCH, HEAD or OPTIONS) and what path the Resource uses. If you click on the Resource you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean. There is also a 'Try' button which enables you to try the Resource out direct from the Developer Portal.If the API requires a client ID or a client secret for identification then you can specify these at the top of the 'Try' section.

    Note: You need to have a valid subscription to test an API.

    Also see:

     

Last Updated: 
Tuesday, May 30, 2017