Basics

API Development 101

A collection of primers on basic concepts related to developing with APIs.

SDKs and code samples

SDKs are libraries of code that contain functions and classes that interact with an API. Square Connect SDKs are available on Github for:

We strongly recommend installing and using the Connect SDKs to interact with Square APIs. Using the SDKs saves you time and makes your applications more secure. For example, if you are developing in PHP and you want to make a Charge request, you can install our PHP SDK and use the \SquareConnect\Model\ChargeRequest to create a request object instead of creating a raw JSON object and writing your own REST request code from scratch.

Sample applications

We also have sample apps that demonstrate the use of Square APIs and SDKs. A good way to get to know the Square APIs and SDKs is to download these sample applications, configure them with your sandbox credentials, and run them. You can also modify sample applications instead of building your own app from scratch.

See Sample Apps for more information.

Best practices for collecting information

If you collect, or plan to collect, personal information from your customers, it is important to handle their data responsibly. Personal information includes obvious things like an email address, phone number, device identifier, physical location, and spending habits. But even less obvious information like zip code or typical commute time can be combined to help identify a person without their consent.

  • Collect the minimum amount of personal information necessary to provide the desired functionality. For example, if you only use email to communicate with site visitors, there is no reason to also collect phone numbers.
  • Always use opt-in instead of opt-out. Let customers consent to sharing their data rather than collecting their data by default. For example, include a checkbox asking for permission to collect contact information and leave it unchecked by default.
  • Avoid persistent caching or storage of PII, including in logs. Do not keep the information for longer than you have to. The easiest way to avoid unintentionally exposing sensitive information is to delete it when you no longer need it.
  • Avoid sharing any personally identifiable information (PII) or location information with third parties. When customers give you permission to collect and save their information, there is an expectation that the information will be kept safe and not be shared with others. Sharing their information with a third party without asking for explicit permission violates those expectations. You may be complicit should the third party handle the information irresponsibly.
  • Encrypt customer information in transit. Secure your website traffic with HTTPS and TLS. If you are unfamiliar with HTTPS and TLS, we recommend reading our HTTPS Overview for more information.

TLS and HTTPS

Transport Layer Security (TLS) — previously known as Secure Socket Layer (SSL) — is the industry standard process for securing network traffic. HTTPS calls are simply HTTP calls made over a connection secured with TLS.

HTTPS is required for all calls to Square endpoints. Read more about TLS and HTTPS.

OAuth

OAuth is a process for securely managing authentication and account access. With OAuth, users can grant or deny access to specific resources without giving out their passwords or granting access to their entire account.

OAuth is required for applications that support multiple Square accounts. But, we recommend using OAuth whenever possible, even when building a single-user application.

Read more about OAuth and the Square OAuth API

Frontend vs. Backend

The frontend–backend model is a way of organizing an application's workload and sharing it across multiple services or infrastructure layers. Understanding the typical roles of frontends and backends is useful for understanding and following along with our API guides.

Read more about frontend vs. backend.

Idempotency

An API call or operation is idempotent if it has the same result no matter how many times it is applied. Idempotency is meant to guard against accidental duplicate calls, particularly when duplicate calls can have negative consequences (for example, with payments or refunds).

Read more about idempotency.

Pagination

API endpoints can return large sets of information. Well designed APIs paginate their responses to make them easier for the calling service to handle. You may need to come up with a strategy to handle pagination and fully process the results.

Read more about pagination and how Square endpoints paginate.

Webhooks

Webhooks (also known as web callbacks or push APIs) are HTTP calls or snippets of code that are triggered by specific events. With a typical API, you have to make calls at regular time intervals to detect changes to your data. Webhooks replace regular API calls with instant, real-time notifications.

Read more about webhooks.

Next
Frontend vs. Backend >

Ask for help on Stack Overflow or join our Slack channel