bbc-news-swift

A Swift client and unofficial documentation for the BBC News API.

This project is for educational and research purposes only.

Installation

bbc-news-swift can be installed using Swift Package Manager by adding the following to your Package.swift file:

.package(url: "https://github.com/bilaalrashid/bbc-news-swift.git", .upToNextMajor(from: "0.0.0"))

Usage

Fetching data

import BbcNews

let bbcNews = BbcNews()
// or
let bbcNews = BbcNews(modelIdentifier: "iPhone15,2", systemName: "iOS", systemVersion: "17.0")

// Get results from the home page
let results = try await bbcNews.fetchIndexDiscoveryPageThrowing(postcode: "W1A")

// Get results from a topic page
let results = try await bbcNews.fetchTopicDiscoveryPageThrowing(for: "c50znx8v8y4t")

// Parse story promo from a set of discovery results and fetch the full contents of that story
for item in results.data.items {
    if case .storyPromo(let storyPromo) = item {
        let url = storyPromo.link.destinations[0].url 

        // Get the full contents of the story
        let story = try await bbcNews.fetchThrowing(url: url) 
    }
}

Swift 5 Result type

All methods have equivalents to support both the Swift 5 Result type and traditional try-catch. You can use the try-catch equivalents by appending Throwing to the end of a method name.

try-catch:

let results = try await bbcNews.fetchIndexDiscoveryPageThrowing(postcode: "W1A")
print(results) // [...]

Result type:

let result = await bbcNews.fetchIndexDiscoveryPage(postcode: "W1A")
switch result {
case .success(let results):
    print(results) // [...]
case .failure(let error):
    print(error)
}

Utilities

import BbcNews

// Check if a URL is part of the BBC News API
BbcNews.isApiUrl(url: URL(string: "https://bbc.co.uk")!) // false

// Convert a webpage URL to a URL for the API
BbcNews.convertWebUrlToApi(url: URL(string: "https://www.bbc.com/news/articles/c289n8m4j19o")!) // https://news-app.api.bbc.co.uk/fd/app-article-api?clientName=Chrysalis&clientVersion=pre-7&page=https://www.bbc.com/news/articles/c289n8m4j19o

Development

This project uses SwiftLint to enforce coding style. You can check for any style violations and attempt to fix them using:

swiftlint --config .swiftlint.yml --strict [--fix]

The test suite uses local files in the tests resources bundle. This causes tests to fail in Xcode, so tests must be run from the command line.

swift test

Full contributing guidelines can be found in CONTRIBUTING.md.

OpenAPI

Documentation of the API is defined using OpenAPI and automatically built using the CI (accessible at https://bilaalrashid.github.io/bbc-news-swift).

These schema files can be linted using Redocly:

redocly lint openapi/*/openapi.yaml

Changes to these files can be visualised by generating a pageset:

redocly build-docs openapi/<version>/openapi.yaml