WriteFreely Documentation Beta

Class WFClient 

public class WFClient

Initializers

init(for:​with:​) 

public init(for instanceURL: URL, with session: URLSessionProtocol = URLSession.shared)

Initializes the WriteFreely client.

Required for connecting to the API endpoints of a WriteFreely instance.

Parameters

instance​URL URL

The URL for the WriteFreely instance to which we're connecting, including the protocol.
session URLSession​Protocol

The URL session to use for connections; defaults to URLSession.shared.

Properties

request​URL 

public var requestURL: URL

user 

public var user: WFUser?

Methods

create​Collection(token:​with​Title:​alias:​completion:​) 

public func createCollection(
        token: String? = nil,
        withTitle title: String,
        alias: String? = nil,
        completion: @escaping (Result<WFCollection, Error>) -> Void
    )

Creates a new collection.

If only a title is given, the server will generate and return an alias; in this case, clients should store the returned alias for future operations.

Parameters

token String?

The access token for the user creating the collection.
title String

The title of the new collection.
alias String?

The alias of the collection.
completion @escaping (Result<WFCollection, Error>) -> Void

A handler for the returned WFCollection on success, or Error on failure.

get​Collection(token:​with​Alias:​completion:​) 

public func getCollection(
        token: String? = nil,
        withAlias alias: String,
        completion: @escaping (Result<WFCollection, Error>) -> Void
    )

Retrieves a collection's metadata.

Collections can be retrieved without authentication. However, authentication is required for retrieving a private collection or one with scheduled posts.

Parameters

token String?

The access token for the user retrieving the collection.
alias String

The alias for the collection to be retrieved.
completion @escaping (Result<WFCollection, Error>) -> Void

A handler for the returned WFCollection on success, or Error on failure.

delete​Collection(token:​with​Alias:​completion:​) 

public func deleteCollection(
        token: String? = nil,
        withAlias alias: String,
        completion: @escaping (Result<Bool, Error>) -> Void
    )

Permanently deletes a collection.

Any posts in the collection are not deleted; rather, they are made anonymous.

Parameters

token String?

The access token for the user deleting the collection.
alias String

The alias for the collection to be deleted.
completion @escaping (Result<Bool, Error>) -> Void

A hander for the returned Bool on success, or Error on failure.

get​Posts(token:​in:​completion:​) 

public func getPosts(
        token: String? = nil,
        in collectionAlias: String? = nil,
        completion: @escaping (Result<[WFPost], Error>) -> Void
    )

Retrieves an array of posts.

If the collectionAlias argument is provided, an array of all posts in that collection is retrieved; if omitted, an array of all posts created by the user whose access token is provided is retrieved.

Collection posts can be retrieved without authentication; however, authentication is required for retrieving a private collection or one with scheduled posts.

Parameters

token String?

The access token for the user retrieving the posts.
collection​Alias String?

The alias for the collection whose posts are to be retrieved.
completion @escaping (Result<[WFPost], Error>) -> Void

A handler for the returned [WFPost] on success, or Error on failure.

move​Post(token:​post​Id:​with:​to:​completion:​) 

public func movePost(
        token: String? = nil,
        postId: String,
        with modifyToken: String? = nil,
        to collectionAlias: String?,
        completion: @escaping (Result<Bool, Error>) -> Void
    )

Moves a post to a collection.

Parameters

token String?

The access token for the user moving the post to a collection.
post​Id String

The ID of the post to add to the collection.
modify​Token String?

The post's modify token; required if the post doesn't belong to the requesting user. If collectionAlias is nil, do not include a modifyToken.
collection​Alias String?

The alias of the collection to which the post should be added; if nil, this removes the post from any collection.
completion @escaping (Result<Bool, Error>) -> Void

A handler for the returned Bool on success, or Error on failure.

pin​Post(token:​post​Id:​at:​in:​completion:​) 

public func pinPost(
        token: String? = nil,
        postId: String,
        at position: Int? = nil,
        in collectionAlias: String,
        completion: @escaping (Result<Bool, Error>) -> Void
    )

Pins a post to a collection.

Pinning a post to a collection adds it as a navigation item in the collection/blog home page header, rather than on the blog itself. While the API endpoint can take an array of posts, this function only accepts a single post.

Parameters

token String?

The access token of the user pinning the post to the collection.
post​Id String

The ID of the post to be pinned.
position Int?

The numeric position in which to pin the post; if nil, will pin at the end of the list.
collection​Alias String

The alias of the collection to which the post should be pinned.
completion @escaping (Result<Bool, Error>) -> Void

A handler for the Bool returned on success, or Error on failure.

unpin​Post(token:​post​Id:​from:​completion:​) 

public func unpinPost(
        token: String? = nil,
        postId: String,
        from collectionAlias: String,
        completion: @escaping (Result<Bool, Error>) -> Void
    )

Unpins a post from a collection.

Removes the post from a navigation item and puts it back on the blog itself. While the API endpoint can take an array of posts, this function only accepts a single post.

Parameters

token String?

The access token of the user un-pinning the post from the collection.
post​Id String

The ID of the post to be un-pinned.
collection​Alias String

The alias of the collection to which the post should be un-pinned.
completion @escaping (Result<Bool, Error>) -> Void

A handler for the Bool returned on success, or Error on failure.

create​Post(token:​post:​in:​completion:​) 

public func createPost(
        token: String? = nil,
        post: WFPost,
        in collectionAlias: String? = nil,
        completion: @escaping (Result<WFPost, Error>) -> Void
    )

Creates a new post.

Creates a new post. If a collectionAlias is provided, the post is published to that collection; otherwise, it is posted to the user's Drafts.

Parameters

token String?

The access token of the user creating the post.
post WFPost

The WFPost object to be published.
collection​Alias String?

The collection to which the post should be published.
completion @escaping (Result<WFPost, Error>) -> Void

A handler for the WFPost object returned on success, or Error on failure.

get​Post(token:​by​Id:​completion:​) 

public func getPost(
        token: String? = nil,
        byId postId: String,
        completion: @escaping (Result<WFPost, Error>) -> Void
    )

Retrieves a post.

The WFPost object returned may include additional data, including page views and extracted tags.

Parameters

token String?

The access token of the user retrieving the post.
post​Id String

The ID of the post to be retrieved.
completion @escaping (Result<WFPost, Error>) -> Void

A handler for the WFPost object returned on success, or Error on failure.

get​Post(token:​by​Slug:​from:​completion:​) 

public func getPost(
        token: String? = nil,
        bySlug slug: String,
        from collectionAlias: String,
        completion: @escaping (Result<WFPost, Error>) -> Void
    )

Retrieves a post from a collection.

Collection posts can be retrieved without authentication. However, authentication is required for retrieving a post from a private collection.

The WFPost object returned may include additional data, including page views and extracted tags.

Parameters

token String?

The access token of the user retrieving the post.
slug String

The slug of the post to be retrieved.
collection​Alias String

The alias of the collection from which the post should be retrieved.
completion @escaping (Result<WFPost, Error>) -> Void

A handler for the WFPost object returned on success, or Error on failure.

update​Post(token:​post​Id:​updated​Post:​with:​completion:​) 

public func updatePost(
        token: String? = nil,
        postId: String,
        updatedPost: WFPost,
        with modifyToken: String? = nil,
        completion: @escaping (Result<WFPost, Error>) -> Void
    )

Updates an existing post.

Note that if the updatedPost object is provided without a title, the original post's title will be removed.

Parameters

token String?

The access token for the user updating the post.
post​Id String

The ID of the post to be updated.
updated​Post WFPost

The WFPost object with which to update the existing post.
modify​Token String?

The post's modify token; required if the post doesn't belong to the requesting user.
completion @escaping (Result<WFPost, Error>) -> Void

A handler for the WFPost object returned on success, or Error on failure.

delete​Post(token:​post​Id:​with:​completion:​) 

public func deletePost(
        token: String? = nil,
        postId: String,
        with modifyToken: String? = nil,
        completion: @escaping (Result<Bool, Error>) -> Void
    )

Deletes an existing post.

Parameters

token String?

The access token for the user deleting the post.
post​Id String

The ID of the post to be deleted.
modify​Token String?

The post's modify token; required if the post doesn't belong to the requesting user.
completion @escaping (Result<Bool, Error>) -> Void

A handler for the Bool object returned on success, or Error on failure.

login(username:​password:​completion:​) 

public func login(username: String, password: String, completion: @escaping (Result<WFUser, Error>) -> Void)

Logs the user in to their account on the WriteFreely instance.

On successful login, the WFClient's user property is set to the returned WFUser object; this allows authenticated requests to be made without having to provide an access token.

It is otherwise not necessary to login the user if their access token is provided to the calling function.

Parameters

username String

The user's username.
password String

The user's password.
completion @escaping (Result<WFUser, Error>) -> Void

A handler for the WFUser object returned on success, or Error on failure.

logout(token:​completion:​) 

public func logout(token: String? = nil, completion: @escaping (Result<Bool, Error>) -> Void)

Invalidates the user's access token.

Parameters

token String?

The token to invalidate.
completion @escaping (Result<Bool, Error>) -> Void

A handler for the Bool object returned on success, or Error on failure.

get​User​Data(token:​completion:​) 

public func getUserData(token: String? = nil, completion: @escaping (Result<Data, Error>) -> Void)

Retrieves a user's basic data.

Parameters

token String?

The access token for the user to fetch.
completion @escaping (Result<Data, Error>) -> Void

A handler for the Data object returned on success, or Error on failure.

get​User​Collections(token:​completion:​) 

public func getUserCollections(token: String? = nil, completion: @escaping (Result<[WFCollection], Error>) -> Void)

Retrieves a user's collections.

Parameters

token String?

The access token for the user whose collections are to be retrieved.
completion @escaping (Result<[WFCollection], Error>) -> Void

A handler for the [WFCollection] object returned on success, or Error on failure.