Creating and Parsing URL’s with NSURLComponents and NSURLQueryItems

In traditional way, we are creating our API URL’s with formatted strings for some years. We have our format ready, setting parameters and create the URL. This way can be easy but if you do not check the format, you can create wrong URL’s easily. Also, something like this is not good for your eyes;
NSURL *url = [NSURL URLWithString:[NSString stringWithFormat:@"", version, userName, password, email, name, gender, isSubscriber]];

What is 3rd %@? Where is name‘s placeholder?

Creating URL’s from string might be working but is very fragile. If you forgot one & character, URL can be nil and your data will not send to server. In some scenarios, your application could be crashed.


An NSURL object represents a URL that can potentially contain the location of a resource on a remote server, the path of a local file on disk, or even an arbitrary piece of encoded data.

Structure of an URL contains elements like scheme, port, user, host, path, query and some more. These elements come together for creating a valid URL. Here are some valid URL’s;


If you need to create an URL, you can use traditional way, or you can do like this;

We used NSURLComponents and NSURLQueryItems for creating our URL.


The NSURLComponents class is a class that is designed to parse URLs based on RFC 3986 and to construct URLs from their constituent parts.

NSURLComponents is parts of an URL. We can retrieve parts or create a new URL with components described below.

  • scheme: Scheme of the URL. e.g., https or ftp
  • user: User of the URL that requires authentication info. e.g., https://admin:123456@…
  • password: Password of the authentication info. e.g., https://admin:123456@…
  • host: Host of the URL. e.g.,
  • port: Port of the Host. e.g.,
  • path: Path of the URL. e.g.,
  • query: Query part of the URL. e.g., https://…/v1/login?user=admin&password=123456
  • queryItems: Parsed query of the URL. returns Array of NSQueryItems. (Minimum iOS8)
  • fragment: Fragment part of the URL. e.g.,

For creating NSURLComponents, you can either initialize an empty one,

or use an existing URL.

Lets create an URL and check out NSURLComponents parts of it. Our URL will not be practical but for the sake of learning, we won’t see that.


NSURLQueryItem object represents a single name/value pair for an item in the query portion of a URL. You use query items with the queryItems property of an NSURLComponents object.

You can get queryItems of the URL with NSURLComponents queryItems method. Each query item is a NSQueryItems instance. NSQueryItems got two properties; name and value. name represents left side, value is right side of the queryItem that seperated with equals character (=). Lets see it in action.

Last Words

Using NSURLComponents and NSQueryItems is more error-proof way for creating your URL’s. Before starting developing new methods to tasks that you do everyday, check some documentation. You may surprise that Foundation classes have some nice utilities like NSURLComponents or NSQueryItems.

See you until i have time to write next post.


Leave a Reply

Your email address will not be published. Required fields are marked *