<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.2.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/URLProtocol",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSURLProtocol"
  },
  "title" : "URLProtocol"
}
-->

# URLProtocol

An abstract class that handles the loading of protocol-specific URL data.

```
class URLProtocol
```

## Overview

Don’t instantiate a [`URLProtocol`](/documentation/Foundation/URLProtocol) subclass directly. Instead, create subclasses for any custom protocols or URL schemes that your app supports. When a download starts, the system creates the appropriate protocol object to handle the corresponding URL request. You define your protocol class and call the [`registerClass(_:)`](/documentation/Foundation/URLProtocol/registerClass(_:)) class method during your app’s launch time so that the system is aware of your protocol.

> Note:
> You cannot use this class to define custom URL schemes and protocols in watchOS 2 and later.

To support the customization of protocol-specific requests, create extensions to the [`URLRequest`](/documentation/Foundation/URLRequest) class to provide any custom API that you need. You can store and retrieve protocol-specific request data by using [`URLProtocol`](/documentation/Foundation/URLProtocol)’s class methods [`property(forKey:in:)`](/documentation/Foundation/URLProtocol/property(forKey:in:)) and [`setProperty(_:forKey:in:)`](/documentation/Foundation/URLProtocol/setProperty(_:forKey:in:)).

Create a [`URLResponse`](/documentation/Foundation/URLResponse) for each request your subclass processes successfully. You may want to create a custom [`URLResponse`](/documentation/Foundation/URLResponse) class to provide protocol specific information.

### Subclassing notes

When overriding methods of this class, be aware that methods that take a `task` parameter are preferred by the system to those that do not. Therefore, you should override the task-based methods when subclassing, as follows:

Swift:

- Initialization — Override [`init(task:cachedResponse:client:)`](/documentation/Foundation/URLProtocol/init(task:cachedResponse:client:)) instead of or in addition to [`init(request:cachedResponse:client:)`](/documentation/Foundation/URLProtocol/init(request:cachedResponse:client:)). Also override the task-based [`canInit(with:)`](/documentation/Foundation/URLProtocol/canInit(with:)-18gbo) instead of or in addition to the request-based [`canInit(with:)`](/documentation/Foundation/URLProtocol/canInit(with:)-76brg).

Objective-C:

- Initialization — Override [`canInit(with:)`](/documentation/Foundation/URLProtocol/canInit(with:)-18gbo) and [`init(task:cachedResponse:client:)`](/documentation/Foundation/URLProtocol/init(task:cachedResponse:client:)) instead of or in addition to [`canInit(with:)`](/documentation/Foundation/URLProtocol/canInit(with:)-76brg) and [`init(request:cachedResponse:client:)`](/documentation/Foundation/URLProtocol/init(request:cachedResponse:client:)).

## Topics

### Creating protocol objects

[`-  initWithRequest:cachedResponse:client:`](/documentation/Foundation/URLProtocol/init(request:cachedResponse:client:))

Creates a URL protocol instance to handle the request.

[`-  initWithTask:cachedResponse:client:`](/documentation/Foundation/URLProtocol/init(task:cachedResponse:client:))

Creates a URL protocol instance to handle the task.

### Registering and unregistering protocol classes

[`+  registerClass:`](/documentation/Foundation/URLProtocol/registerClass(_:))

Attempts to register a subclass of [`URLProtocol`](/documentation/Foundation/URLProtocol), making it visible to the URL loading system.

[`+  unregisterClass:`](/documentation/Foundation/URLProtocol/unregisterClass(_:))

Unregisters the specified subclass of [`URLProtocol`](/documentation/Foundation/URLProtocol).

### Determining If a subclass can handle a request

[`+  canInitWithRequest:`](/documentation/Foundation/URLProtocol/canInit(with:)-76brg)

Determines whether the protocol subclass can handle the specified request.

[`+  canInitWithTask:`](/documentation/Foundation/URLProtocol/canInit(with:)-18gbo)

Determines whether the protocol subclass can handle the specified task.

### Getting and setting request properties

[`+  propertyForKey:inRequest:`](/documentation/Foundation/URLProtocol/property(forKey:in:))

Fetches the property associated with the specified key in the specified request.

[`+  setProperty:forKey:inRequest:`](/documentation/Foundation/URLProtocol/setProperty(_:forKey:in:))

Sets the property associated with the specified key in the specified request.

[`+  removePropertyForKey:inRequest:`](/documentation/Foundation/URLProtocol/removeProperty(forKey:in:))

Removes the property associated with the specified key in the specified request.

### Providing a canonical version of a request

[`+  canonicalRequestForRequest:`](/documentation/Foundation/URLProtocol/canonicalRequest(for:))

Returns a canonical version of the specified request.

### Determining if requests are cache equivalent

[`+  requestIsCacheEquivalent:toRequest:`](/documentation/Foundation/URLProtocol/requestIsCacheEquivalent(_:to:))

A Boolean value indicating whether two requests are equivalent for cache purposes.

### Starting and stopping downloads

[`-  startLoading`](/documentation/Foundation/URLProtocol/startLoading())

Starts protocol-specific loading of the request.

[`-  stopLoading`](/documentation/Foundation/URLProtocol/stopLoading())

Stops protocol-specific loading of the request.

### Getting protocol attributes

[`cachedResponse`](/documentation/Foundation/URLProtocol/cachedResponse)

The protocol’s cached response.

[`client`](/documentation/Foundation/URLProtocol/client)

The object the protocol uses to communicate with the URL loading system.

[`URLProtocolClient`](/documentation/Foundation/URLProtocolClient)

The interface used by [`URLProtocol`](/documentation/Foundation/URLProtocol) subclasses to communicate with the URL Loading System.

[`request`](/documentation/Foundation/URLProtocol/request)

The protocol’s request.

[`task`](/documentation/Foundation/URLProtocol/task)

The protocol’s task.

## Relationships

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

### Conforms To

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CVarArg`](/documentation/Swift/CVarArg)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)