{"id":1599,"url":"https://github.com/Overcoat/Overcoat","last_synced_at":"2025-08-02T04:31:54.499Z","repository":{"id":8509006,"uuid":"10120283","full_name":"Overcoat/Overcoat","owner":"Overcoat","description":"The perfect accessory for Mantle and AFNetworking.","archived":false,"fork":false,"pushed_at":"2016-10-20T18:14:00.000Z","size":1431,"stargazers_count":1096,"open_issues_count":25,"forks_count":105,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-08-01T05:46:01.760Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Overcoat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-05-17T09:34:10.000Z","updated_at":"2025-06-05T08:22:36.000Z","dependencies_parsed_at":"2022-08-24T13:39:53.073Z","dependency_job_id":null,"html_url":"https://github.com/Overcoat/Overcoat","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/Overcoat/Overcoat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Overcoat%2FOvercoat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Overcoat%2FOvercoat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Overcoat%2FOvercoat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Overcoat%2FOvercoat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Overcoat","download_url":"https://codeload.github.com/Overcoat/Overcoat/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Overcoat%2FOvercoat/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268334614,"owners_count":24233793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-01-05T20:15:51.030Z","updated_at":"2025-08-02T04:31:54.206Z","avatar_url":"https://github.com/Overcoat.png","language":"Objective-C","funding_links":[],"categories":["Networking","Objective-C"],"sub_categories":["Video","Other free courses"],"readme":"# Overcoat\n\n[![Build Status](https://travis-ci.org/Overcoat/Overcoat.svg)](https://travis-ci.org/Overcoat/Overcoat)\n[![Cocoapods Compatible](https://img.shields.io/cocoapods/v/Overcoat.svg)](https://cocoapods.org/pods/Overcoat)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n\n### We are finding maintainers, contact @sodastsai :)\n\nOvercoat is a small but powerful library that makes creating REST clients simple and fun.\nIt provides a simple API for making requests and mapping responses to model objects.\n\nOvercoat is built on top of [AFNetworking](https://github.com/AFNetworking/AFNetworking) and\nuses [Mantle](https://github.com/Mantle/Mantle) to map responses into plain or Core Data model objects.\n\nIf you need to learn more about Mantle, we recommend these resources:\n\n1. [Introduction](https://github.com/Mantle/Mantle/blob/master/README.md).\n2. [Better Web Clients with Mantle and AFNetworking](https://speakerdeck.com/gonzalezreal/better-web-clients-with-mantle-and-afnetworking).\n\n**Overcoat 4.0** is the latest major release and introduces several API-breaking changes to\nsupport envelop and error responses, Core Data serialization, and a new method to specify how to\nmap responses to model objects.\n\nIf you are upgraded from Overcoat 3.x, check [the migration note]( https://github.com/Overcoat/Overcoat/blob/master/CHANGELOG.md#migrate-from-3x)\n\nCheck who's using Overcoat [here](https://github.com/Overcoat/Overcoat/wiki/Who-uses-Overcoat).\nYou're welcome to add your project/app into this wiki page.\n\n\n## Requirements\n\nOvercoat supports OS X 10.9+ and iOS 7.0+.\n\n\n## Installation\n\n### Using CocoaPods\n\nAdd the following to your `Podfile` and run `$ pod install`.\n\n``` ruby\npod 'Overcoat', '~\u003e 4.0.0-beta.1'\n```\n\nIf you don't have CocoaPods installed or integrated into your project,\nyou can learn how to do so [here](http://cocoapods.org).\n\n### Using Carthage\n\nAdd the following to your `Cartfile` and run `$ carthage update`.\n\n```\ngithub \"Overcoat/Overcoat\" \"4.0.0-beta.1\"\n```\n\nIf you don't have Carthage installed or integrated into your project,\nyou can learn how to do so [here](https://github.com/Carthage/Carthage).\n\n\n## Sample Code\n\nOvercoat includes a simple [Twitter](https://dev.twitter.com/docs/api/1.1) client that shows some new features:\n\n* Mapping model classes to resource paths.\n* Specifying an error model class.\n* Core Data serialization.\n* Promises.\n\nYou can find the sample code [here](https://github.com/Overcoat/TwitterTimelineExample).\nNote that you'll need to run `pod install` to install all the dependencies.\n\n\n## Usage\n\n### Creating a Client Class\nOvercoat provides 2 different classes to subclass when creating your own clients:\n\nClass                                   | Usage\n----------------------------------------|---------------------------------------------------\n`OVCHTTPSessionManager`                 | Using with NSURLSession and Mantle\n`OVCManagedHTTPSessionManager`          | Using with NSURLSession, Mantle, and CoreData. This is also a subclass of `OVCHTTPSessionManager`\n\nBoth classes have identical APIs.\n\n```objc\n#import \u003cOvercoat/Overcoat.h\u003e\n\n@interface TwitterClient : OVCHTTPSessionManager\n...\n@end\n```\n\n### Specifying Model Classes\n\nTo specify how responses should be mapped to model classes you must override `+modelClassesByResourcePath`\nand return a dictionary mapping resource paths to model classes.\n\n```objc\n+ (NSDictionary *)modelClassesByResourcePath {\n    return @{\n        @\"statuses/*\": [Tweet class],\n        @\"users/*\": [TwitterUser class],\n        @\"friends/ids.json\": [UserIdentifierCollection class],\n        @\"followers/ids.json\": [UserIdentifierCollection class]\n    };\n}\n```\n\nYou don't need to specify the full path, and you can use `*` and `**` to match any text or `#` to match only digits.\n\nIf you use `*` and `#`, they are **strict path matchings**, so **the number of path components must be equal**. The `**` just matches any text and has no path components number limitation.\n\nMatch String          | Path                           | Result\n--------------------- | ------------------------------ | --------\n`statuses/*`          | `statuses/user_timeline`        | Matched\n`statuses/#`          | `statuses/user_timeline`        | Missed (wrong type, the path component after `statuses` should be dights only)\n`statuses/*`          | `statuses/retweets/12345`       | Missed (wrong number of path components, there should be only one  path component after `statuses`)\n`statuses/*/*`        | `statuses/retweets/12345`       | Matched\n`statuses/**`         | `statuses/retweets/12345`       | Matched\n`statuses/**`         | `statuses/retweets/12345/extra` | Matched (the number of path components doesn't matter)\n`statuses/retweets/*` | `statuses/retweets/12345`       | Matched\n`statuses/retweets/#` | `statuses/retweets/12345`       | Matched\n\n\nAlso you can specify different model classes by request method or response status code, like:\n\n```objc\n+ (NSDictionary *)modelClassesByResourcePath {\n    return @{\n        @\"statuses/*\": [Tweet class],\n        @\"users/*\": @{\n            @\"PUT\": [UpdatedTwitterUser class],  // For PUT request method,\n            @\"201\": [NewCreatedTwitterUser class],  // For 201 response status code\n            @\"*\": [TwitterUser class],  // For all other cases, as fallback\n        },\n        @\"friends/ids.json\": [UserIdentifierCollection class],\n        @\"followers/ids.json\": [UserIdentifierCollection class]\n    };\n}\n```\n\nCheck the documentation of `OVCURLMatcherNode` for further explaination.\n\n\n### Envelop and Error Responses\n\nDifferent REST APIs have different ways of dealing with status and other metadata.\n\nPure REST services like **Twitter** use HTTP status codes and a specific JSON response to communicate errors;\n and HTTP headers for other metadata like rate limits. For these kind of services, you may want to override\n `+errorModelClassesByResourcePath` to map error responses into your own model.\n\n```objc\n+ (Class)errorModelClassesByResourcePath {\n    return @{@\"**\": [TwitterErrorResponse class]};\n}\n```\n\nOther services like **App.net** use an envelop response, which is a top level JSON response containing\nthe data requested and additional metadata. For these kind of services, you must create your own `OVCResponse`\nsubclass and specify the data key path.\n\n```objc\n@interface AppDotNetResponse : OVCResponse\n...\n@end\n\n@implementation AppDotNetResponse\n+ (NSString *)resultKeyPathForJSONDictionary:(NSDictionary *)JSONDictionary {\n    return @\"data\";\n}\n@end\n```\n\nYou can then specify which response class to use in your client by overriding `+responseClassesByResourcePath`.\n\n```objc\n+ (Class)responseClassesByResourcePath {\n    return @{@\"**\": [AppDotNetResponse class]};\n}\n```\n\n### Core Data Serialization\n\nTo support CoreData serialization, you have to use `Overcoat+CoreData` extension if you're using CocoaPods\n\n``` ruby\npod 'Overcoat+CoreData', '~\u003e 4.0'  # Use this,\n```\n\nOr if you are using Carthage, you also have to add `OvercoatCoreData.framework` to your project.\n\nAnd the main classes would be changed to `OVCManaged` prefixed one. (For instance,\n`OVCHTTPSessionManager` -\u003e `OVCManagedHTTPSessionManager`)\n\nIf you initialize your client with a valid `NSManagedObjectContext`,\nit will automatically persist any model object(s) parsed from a response,\nif the model supports Core Data serialization (that is, implements `MTLManagedObjectSerializing`).\n\nNote that, if you provide a context with an `NSMainQueueConcurrencyType`,\na private context will be created to perform insertions in the background.\n\nYou can see Core Data Serialization in action in the [provided example](https://github.com/Overcoat/TwitterTimelineExample).\n\n\n### Making HTTP Requests\n\n```objc\n// Lookup Twitter users\nNSDictionary *parameters = @{\n    @\"screen_name\": @\"gonzalezreal\",\n    @\"user_id\": @\"42,3141592\"\n};\n\n[twitterClient GET:@\"users/lookup.json\" parameters:parameters completion:^(OVCResponse *response, NSError *error) {\n    NSArray *users = response.result; // This is an array of TwitterUser objects!\n}];\n```\n\nNote that Overcoat automatically parses the JSON into model objects, that is, in this case `response.result`\ncontains an array of `TwitterUser` objects.\n\n#### ReactiveCocoa\n\nFrom 2.0, Overcoat adds support for [ReactiveCocoa](https://github.com/ReactiveCocoa/ReactiveCocoa).\n\nTo add ReactiveCocoa support, you have to use `Overcoat+ReactiveCocoa` podspec if you're using CocoaPods.\nOr if you're using Carthage, add `OvercoatReactiveCocoa.framework`\n\nNow you can make HTTP requests and get cold signals to handle responses:\n\n```objc\n#import \u003cOvercoatReactiveCocoa/OvercoatReactiveCocoa.h\u003e\n...\n[[twitterClient rac_GET:@\"users/lookup.json\" parameters:parameters] subscribeNext:^(OVCResponse *response) {\n    ...\n} error:^(NSError *e) {\n    ...\n}];\n```\n\n#### PromiseKit\n\nIf you're looking for a better way to handle asynchronous calls but you're not ready to embrace ReactiveCocoa,\nyou may try [PromiseKit](http://promisekit.org).\n\nTo add PromiseKit support, you have to use `Overcoat+PromiseKit` podspec if you're using CocoaPods.\nOr if you're using Carthage, add `OvercoatPromiseKit.framework`\n\nNow you can get `PMKPromise` objects when making HTTP requests:\n\n```objc\n#import \u003cOvercoatPromiseKit/OvercoatPromiseKit.h\u003e\n...\n[twitterClient pmk_GET:@\"users/lookup.json\" parameters:parameters].then(^(OVCResponse *response) {\n    return response.result;\n});\n```\n\n## Testing the library\n\nIn order to build the library and run unit tests, you will first need to install 2 tools: `cocoapods` and `xctool`\n* cocoapods: https://cocoapods.org\n* xctool: https://github.com/facebook/xctool\n\nAfter you setup these tools (or you already have these tools), you could run tests via\n```bash\nmake test\n```\n\nCheck the `Makefile` to run other test target.\n\n## Contact\n\n* [Guillermo Gonzalez](https://github.com/gonzalezreal), [@gonzalezreal](https://twitter.com/gonzalezreal)\n* [sodastsai](https://github.com/sodastsai), [@sodastsai](https://twitter.com/sodastsai)\n\n## License\n\nOvercoat is available under the MIT license.\nSee [LICENSE.md](https://github.com/gonzalezreal/Overcoat/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOvercoat%2FOvercoat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOvercoat%2FOvercoat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOvercoat%2FOvercoat/lists"}