API Glossary & 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.

To visit the API Directory, click here.

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.
• cURL is 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. For more information on JSON, see here.
• 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.
• 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 200 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 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.
• Developer Organization A Developer Organization owns applications that subscribe to APIs. Application developers can belong to one or more Developer Organizations. A Developer Organization has one owner who manages the membership in the organization. Developer Organization membership at U-M is based on department affiliation. Refer to the API Directory's Getting Started page for information about joining a Developer Organization.
• Provider Organization A Provider Organization is the entity which owns APIs and associated Plans. Provider organizations at U-M are based on the U-M data domains. Data stewards assist with oversight of the APIs in a data domain. A Provider Organization has an owner who helps to manage the membership in the organization. Refer to the API Directory's Getting Started page for information about joining a Provider Organization.

Frequently Asked Questions

Consuming an API

What is an API?

An API is an interface that makes it easy for one application to consume capabilities or data from another application. By defining stable, simplified entry points to application logic and data, APIs enable developers to easily access and reuse application logic built by other developers. In the case of Web APIs, that logic and data is exposed over the network.

Since applications that consume APIs are sensitive to changes, APIs also imply a contract. The contract provides some level of assurance that, over time, the API will change in a predictable manner.

Who is allowed to consume an API?

University of Michigan students, faculty, staff, and sponsored affiliates are all granted access to the API Directory for academic, educational, administrative, or research purposes. All users are responsible to comply with the API Directory [Terms & Conditions]

How do I get started consuming APIs?

To get started with the API Directory, visit the Getting Started page.

Are there any usage limits?

In general, API within the API Directory have a quota of 200 calls per minute for each app. Any additional restrictions or policies will be individually documented within the Directory.

Who can I contact with questions or issues?

If you have questions or issues, please reach out to the API Directory Team for support.

 

Developing & Publishing an API

How can I list my own API in the API Directory?

To get started in developing, join the API Developers MCommunity group. Review the API Developer Training Materials to get familiar with API Development practices at U-M.

Once you are a member of the API Developers group, you will be granted access to the dev and test environments for the API Directory, where you will be able to build and test your own API proxies.

If you have questions, please reach out to the API Directory Team for support.

How are APIs secured?

At the transport level, all API traffic is secured by TLS, ensuring end-to-end encryption between the API Directory and consumers.

The API Directory is hosted by Google within a virtual private cloud, ensuring secure communication between the API Directory runtimes and backend services.

At the application level, all APIs are secured by two-legged OAuth. Traffic is managed by quota policies tied to each application and additional security policies block malicious requests and mitigate sudden spikes in traffic.

Each developer application is tied to a U-M affiliated user or a team of U-M affiliated users. Application credentials can be issued and revoked by end-users as well as API admins and APIs can require approval before a subscription is granted.

Who controls access to each API?

While the ITS API Directory team has ultimate control over who is allowed to access APIs within the API Directory, users are allowed to self-manage their own API Teams through the API Portal.

Subscription requests are handled by ITS and will require approval from the appropriate stakeholders and data stewards before subscriptions are authorized.

Is there a development environment?

The API Directory has both a dev and test environment for developers to use as they develop their APIs. Developers should start building their API proxies in the dev environment before promoting their code to the test environment for QA testing. In each environment, extensive debug tools are available to aid in development efforts.

How can I audit & monitor my API’s traffic?

The API Directory offers API Developers basic reports on traffic by product/proxy within the developer console. All API traffic is logged via Google Cloud Logging and sent to Splunk. If you have additional needs for logging and analytics, please contact the API Directory Team for support.

What is an API proxy?

You expose an API on the API Directory by implementing one or more API proxies. API proxies decouple the app-facing API from your backend services, shielding these apps from backend code changes. As you make backend changes to your services, apps continue to call the same API without any interruption.

What is an API product?

As an API provider, you create API products to bundle your APIs and make them available to app developers for consumption. You can think of API products as your product line.

Specifically, an API product bundles together one or more operations. An operation specifies an API proxy and resource paths that can be accessed on that proxy. An operation can also limit access by HTTP methods and by quota.

API products are the central mechanism for access control to your APIs. By defining one or more API products in a developer app, you can restrict access to proxies with an API key. In Apigee, API keys are provisioned, not for APIs themselves, but for API products. In other words, API keys are provisioned for bundles of operations that define a product line or specific service plan.