What is an API?

An Application Programming Interface (API) is a software to software interface, not a user interface. It is a way to interact with an application/service or data. Typically it refers to web APIs which provide an easy way for developers to enable software applications to communicate with remote applications over the internet through a series of calls. Calls back and forth between the applications are managed through web services.

How can I find out what APIs are on the UCSF API Portal?

Access https://anypoint.mulesoft.com/apiplatform/ucsf#/portals (you’ll need to log in with your MyAccess login). Click on any API to review the documentation.

What are the benefits of publishing my APIs on the UCSF API Portal?

  • Open Up Your Data to UCSF Developers
    • Adding your API to the UCSF API Portal makes it easy for anyone across UCSF to discover your API in the central repository.
    • You will know when someone wants to use your API as you will receive an access request.
    • On receipt of the access request you can determine whether you grant access to your data. You have complete control over API access.
    • Integration Services can create Mule applications to proxy your existing APIs.
    • The portal can be used to provide interactive documentation for your APIs.
    • The portal can be used as a sandbox for testing your API.
    • Daisy chain or orchestrate data with other available APIs.
    • Provide consistency for data consumers.
  • Complete API Management Solution
    • Accessible to UCSF users through MyAccess Single Sign On.
    • Manage all your APIs using a single platform.
    • Apply runtime policies.
    • Define and enforce SLA tiers for your APIs.
    • Manage API versions.
      • Clients are loosely coupled (reduce interdependencies) to the API implementation.
    • Security
      • Protect your API’s - Require or restrict certain behaviors with prebuilt policies.
      • Integration Services team can help you build custom policies if needed.
      • Add or remove policies around security, throttling and rate limiting, to protect your resources and usages.
      • Monitor users and traffic.
      • Different options for API authentication based on the level of security needed.
    • Analytics
      • Access to data for analytics.
      • Requests by Date.
      • Requests by Location.
      • Requests by Application.
      • Requests by Platform.
      • Integration Services team can build custom charts if needed.
    • Reliability
      • The UCSF API Portal is highly reliable and is on MuleSoft Anypoint Platform.
      • The UCSF API Portal is supported by the Integration Services team in ITS.

Are there best practices I should follow for APIs?

REST resource naming Standard

This website http://www.restapitutorial.com/lessons/restfulresourcenaming.html has a good naming convention for REST resources. Follow these guidelines to name your REST resources.

See Naming Convention for UCSF best practices and additional information.

REST API best practices

Follow http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api for best practices

Rest API Size, Collection Consideration

Payload Size

Since we use a shared infrastructure we must be really careful to not overload our infrastructure and prevent the performance of a single API (critical or non-critical) adversely affecting performance of other critical APIs on the platform.

Please ensure that you use compression when passing large sets of data through APIs.

To prevent memory issues and CPU issues, normal API payload size should not be more than 1 MB in size. In some special cases message payload size can vary and can go up to 10MB - you should discuss these special cases with the ITS Integration Services team as soon as possible during the design/development of your API.

Collection Payload Size

Collection size is calculated by the payload size for each record multiplied by the number of records in the response. Care must be taken to make sure that the maximum payload size of collection doesn't exceed the maximum payload size described above.

Using gzip

An easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.

In order to receive a gzip-encoded response API client should Set HTTP header Accept-Encoding: gzip andyour API should pass back response based on Accept-Encoding header. If the Accept-Encoding is set to gzip, API should compress api response payload and set the HTTP response header to Content-Encoding: gzip

If Accept-Encoding is not set for large payload API, gzip should be used by default.

The following link https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/ provides more information about Encoding and gzip compression.

Offset and Limit

You should never return all the data available in a collection API. Major API providers use different syntax, e.g. page and row, start and count, and page and offset. As a standard for UCSF APIs, wherever possible uselimit=25&offset=50

e.g. /students?limit=25&offset=50 will return 25 record starting from position 50

It is also recommended to set limit to maximum of 1000. In most cases a default of 100 or 200 works well.

Note: All Collection API should implement limit and offset so that they never return more than maximum record size.