nicholastd07/swiftdailyapi

A Swift API framework for ZhiHu's Daily News.

SwiftDailyAPI

An API framework for ZhiHu's Daily News, built in Swift. It is powering my open source App Swift-ZHI which is a newsreader App built for ZhiHu's Daily News.

Requirement

• iOS 8.0+ / Mac OS X 10.9+
• Xcode 7.2 +

Installation

Embedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks (10.9).

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

CocoaPods 0.39.0+ is required to build SwiftDailyAPI 2.0.0+.

To integrate SwiftDailyAPI into your Xcode project using CocoaPods, specify it in your Podfile:

platform :ios, '8.0'
use_frameworks!

pod 'SwiftDailyAPI', '~> 2.0'

Then, run the following command:

$ pod install

Carthage

Add the following to your Cartfile:

github "NicholasTD07/SwiftDailyAPI" ~> 2.0.0 # Swift 2.1
github "NicholasTD07/SwiftDailyAPI" ~> 1.0.0 # Swift 1.2

Then run carthage update.

Follow the current instructions in Carthage's README for up to date installation instructions.

Usage

import SwiftDailyAPI

// Setup
var latestDaily: LatestDaily?
var daily: Daily?
var news: News?
var newsExtra: NewsExtra?
var shortComments, longComments: Comments?

// Given
let newsId = 4772308
let date = NSDate.dateFromString("20150525", format: DailyConstants.dateFormat)!
let api = DailyAPI(userAgent: "SwiftDailyAPI_ReadMe")

// When
api.latestDaily { latestDailyFromAPI in
  latestDaily = latestDailyFromAPI
  print(latestDaily?.news)
  print(latestDaily?.topNews)
}

api.daily(forDate: date) { dailyFromAPI in
  daily = dailyFromAPI
  print(daily?.news)
}

api.news(newsId) { newsFromAPI in
  news = newsFromAPI
  print(news?.newsId)
  print(news?.title)
}

api.newsExtra(newsId) { newsExtraFromAPI in
  newsExtra = newsExtraFromAPI
  print(newsExtra?.popularity)
  print(newsExtra?.comments)
}

api.comments(newsId, shortCommentsHandler: { comments in
  shortComments = comments
  print(shortComments?.comments)
  }, longCommentsHandler: { comments in
    longComments = comments
    print(longComments?.comments)
})

// Then
// expect all vars in `Setup` section to not be nil
// code in `ReadmeCodeSpecs.swift`

This code is tested in ReadmeCodeSpecs.swift. There's also a Then part in the spec which expects all the vars in the Setup to not be nil.

Frameworks

• Alamofire - Elegant HTTP networking
• Argo - Functional JSON parsing
• Quick - Testing
• Nimble - Matcher

Appendix

How does SwiftDailyAPI support both Carthage and CocoaPods while having 3rd parity dependencies?

Well, it works like this. Before 2.0.1, I was using Carthage to manage dependencies so Carthage works for version 2.0.0. However, I switched to CocoaPods since 2.0.1 because it's easier to setup, more stable from my experience, also takes less time to install dependencies (Carthage has one extra build step) and Travis has caching for CocoaPods.

swiftdailyapi's Issues

Create a struct to hold constants

dateFormat = "yyyyMMdd"

Update test when `JSONFromFile` becomes a free function

I see there's a commit in Argo which turns the function from a static class function into a free function. It will cause tests to fail when it is included in a release and we update Argo to that release.

Looks like this Argo is not as easy as ObjectMappper

JUST FYI,

https://github.com/Hearst-DD/ObjectMapper

`class User: Mappable {
var username: String?
var age: Int?
var weight: Double!
var array: [AnyObject]?
var dictionary: [String : AnyObject] = [:]
var bestFriend: User? // Nested User object
var friends: [User]? // Array of Users
var birthday: NSDate?

required init?(_ map: Map) {

}

// Mappable
func mapping(map: Map) {
    username    <- map["username"]
    age         <- map["age"]
    weight      <- map["weight"]
    array       <- map["arr"]
    dictionary  <- map["dict"]
    bestFriend  <- map["best_friend"]
    friends     <- map["friends"]
    birthday    <- (map["birthday"], DateTransform())
}

}`

`commentId` in `Comment`

1. For loading more comments because short comments are paginated.
2. Unique ID in database.

DailyAPI.newsExtras

Should decode JSON on a queue other than `mainQueue`

Add `bin/` files for `carthage` build and archive

example: https://github.com/thoughtbot/Argo/blob/master/bin/archive

Change `Deployment Target` to 8.0

Cocoa Touch Framework requires at least 8.0, iirc.

Add access control for all things(classes, structs, methods, etc.)

`DailyStore` phase one

Store takes a APIType, easier to inject despondency, easier to test.

Log failed decoding of JSON

type: 'news' or 'daily'
id-string: 'id: xxx' or 'date: yyyyMMdd'
json: ...
version: x.y.z
Argo version: x.y.z

Add performance tests for decoing

Document functionalities of each public function in DailyAPI

Get `DailyNews` for a date

Given a user wants DailyNews for a specific date
When the user pass in the date and a handler
When the request and parsing finishes successfully
Then the handler will be called with the DailyNews

Ignore 'Carthage/Build'

Document that every function's `completionHandler` will be called on mainThread

Support Daily Themes

struct BasicNewsMeta { // ThemeNewsMeta
  let newsId: Int
  let title: String
  let imageURLs: [NSURL]?
}

struct Theme { }

enum DailyRouter {
  case themes
  case themeDaily(themeId:)
}

Explain how to use this in document

Explain the parts contained in this framework (parser, downloader), what do they achieve.

Update readme in daily-store-take-2 branch for Xcode 7 + Swift 2

`Cartfile`: "Alamofire/Alamofire" "swift-2"

Change the cartfile to use swift 2 branch in official alamofire branch.

Try refactor methods in `DailyAPI` with a generic func

BUG - Some properties in News are optional

For example, newsId == 4820022 in http://news.at.zhihu.com/api/4/news/before/20150627

• News.image, and News.imageSourceText are optional for a news from a theme, See here: http://news-at.zhihu.com/api/4/news/4820022

News.imageCount

Count the images in the html body

Split `ModelDecodingSpecs` into smaller files

It is getting larger and larger with more models added in.

Some ideas:

• Split by data
  • RealDataModelDecoding
  • TestDataModelDecoding
• Or split by model
  • NewsDecoding
  • DailyDecoding
  • etc.

Highlight Commits

This is a note where I keep all the note worth a second look. Maybe I had an elegant way of solving a problem, maybe I was impressed by Swfit.

DailyAPI.newsContributors(newsId:)

`DailyAPI` -> 2+ `Types`, `DailyAPIStore` conforms to one of it.

• CoreType
  • latestDaily
  • daily
  • news
• MinorType
  • newsExtra
  • shortComments
  • longComments
  • comments

protocol DailyAPIType: CoreType, MinorType { }

Document that `DailyAPI` needs to be kept around to get the response back.

Extend builtin types with `decode` method or add `toType` method

NSURL.decode
toNSDate(format:)(string:)

Isolated spec for `News` with real data

Although DailyAPISpecs test model decoding with real data. However, when the server changes its API, those specs will fail. It would be hard to tell which part of the process failed. Maybe it's network, maybe it's the JSON parsing.

With spec testing on real data, it would be easier and quicker to find out which part fails during a integration test like the ones in DailyAPISpecs.

Rename *DailyNews -> Daily

"Use `final` when you know that a declaration does not need to be overridden"

Increasing Performance by Reducing Dynamic Dispatch

Public interfaces, private implementations

Define types as protocols. Separate interface and implementation.

protocol DailyNews:
  ...

api.request THROWS

enum SwiftDailyError {
  // case NoNetworkError
  case RequestFailedError
  case DecodingError
}

Update README with more example code

Spec for code in readme

No more private lets in Decodable Models

Deal with data transform String -> NSURL, String -> Int in init or, decode

Update dependencies

• carthage update
• xcodebuild clean test
• carthage build ...
• put it into a bin file

DailyAPI.shortComments, longComments, comments

Get `News` for a specific `newsId`

• Decodable News
• DailyAPI.news(newsId:)

Replace all `if let` and `?` with `!` in specs

If everything works as planned, there should be no nils.