You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[📚docs] give the README a bit of fresh paint (#6043)
* update badges
* Rework the main page
* add emojis
* Use link instead of copying the logo everywhere
* wording
* uniformize badges style
* Update README.md
[](http://community.apollographql.com/new-topic?category=Help&tags=mobile,client)
[](https://ge.apollographql.com/scans)
13
10
14
-
| ☑️ Apollo Clients User Survey |
15
-
| :----- |
16
-
| What do you like best about Apollo Kotlin? What needs to be improved? Please tell us by taking a [one-minute survey](https://docs.google.com/forms/d/e/1FAIpQLSczNDXfJne3ZUOXjk9Ursm9JYvhTh1_nFTDfdq3XBAFWCzplQ/viewform?usp=pp_url&entry.1170701325=Apollo+Kotlin&entry.204965213=Readme). Your responses will help us understand Apollo Kotlin usage and allow us to serve you better. |
17
-
18
-
Apollo Kotlin (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL operations.
19
-
20
-
Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.
21
-
22
-
Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
23
-
24
-
This library is designed primarily with Android in mind, but you can use it in any Kotlin (including multiplatform) and Java app.
25
-
26
-
## Features
27
-
28
-
* Kotlin Multiplatform and Java code generation
29
-
* Queries, Mutations and Subscriptions
30
-
* Reflection-free parsing
31
-
* Normalized cache
32
-
* Custom scalar types
33
-
* HTTP cache
34
-
* Auto Persisted Queries
35
-
* Query batching
36
-
* File uploads
37
-
* Fake models for tests
38
-
* AppSync and graphql-ws websockets
39
-
* GraphQL AST parser
40
-
* Plugin for Android Studio and IntelliJ
41
-
42
-
## Multiplatform
43
-
44
-
Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project.
45
-
46
-
Here's the current matrix of supported features per platform:
Check [the project website](https://www.apollographql.com/docs/android/) for in depth documentation.
80
-
81
-
## Getting started
82
-
83
-
If you are new to GraphQL, check out [the tutorial](https://www.apollographql.com/docs/android/tutorial/00-introduction/) that will guide you through building an Android app using Apollo.
84
-
85
-
If you'd like to add Apollo Kotlin to an existing project, follow these steps:
86
-
87
-
Add the plugin to your `build.gradle.kts`:
88
-
89
-
```kotlin
90
-
plugins {
91
-
id("com.apollographql.apollo") version "4.0.0-rc.1"
Set the package name to use for the generated models:
104
-
105
-
```kotlin
106
-
apollo {
107
-
service("service") {
108
-
packageName.set("com.example")
109
-
}
110
-
}
111
-
```
112
-
113
-
Apollo Kotlin supports three types of files:
114
-
-`.graphqls` schema files: describes the types in your backend using the GraphQL syntax.
115
-
-`.json` schema files: describes the types in your backend using the Json syntax.
116
-
-`.graphql` executable files: describes your queries and operations in the GraphQL syntax.
117
-
118
-
By default, Apollo Kotlin requires a schema in your module's `src/main/graphql` directory. You can download a schema using introspection with the `./gradlew downloadApolloSchema` task. Sometimes introspection is disabled and you will have to ask your backend team to provide a schema. Copy this schema to your module:
119
-
120
-
```
121
-
cp ${schema} ${module}/src/main/graphql/
122
-
```
123
-
124
-
Write a query in a `${module}/src/main/graphql/HeroQuery.graphql` file:
[](https://ge.apollographql.com/scans)
135
15
136
-
Build your project. This will generate a `HeroQuery` class that you can use with an instance of `ApolloClient`:
16
+
</div>
137
17
138
-
```kotlin
139
-
// Create a client
140
-
val apolloClient =ApolloClient.Builder()
141
-
.serverUrl("https://example.com/graphql")
142
-
.build()
143
18
144
-
// Execute your query. This will suspend until the response is received.
145
-
val response = apolloClient.query(HeroQuery(id ="1")).execute()
146
-
147
-
println("Hero.name=${response.data?.hero?.name}")
148
-
```
149
-
150
-
**To learn more about other Apollo Kotlin APIs:**
151
-
152
-
* Execute your first [mutation](https://www.apollographql.com/docs/kotlin/essentials/mutations/)
* Factor common patterns using [fragments](https://www.apollographql.com/docs/kotlin/essentials/fragments/)
155
-
156
-
## Requirements
157
-
158
-
Some platforms have specific runtime requirements:
159
-
160
-
* JVM 8+
161
-
* Android API level 21+ (`apollo-http-cache` and `apollo-adapters` require enabling [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26)
162
-
* iOS 13+
163
-
164
-
At build time, it requires:
165
-
166
-
* Gradle 8.0+
167
-
* Kotlin 1.9+ for JVM projects
168
-
* Kotlin 2.0+ for native, JS, and Wasm projects
169
-
170
-
## Proguard / R8 configuration
171
-
172
-
As the code generated by Apollo Kotlin doesn't use any reflection, it can safely be optimized / obfuscated by Proguard or R8, so no particular exclusions need to be configured.
173
-
174
-
## Android Studio / IntelliJ plugin
175
-
176
-
A [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
177
-
178
-
Installation instructions and more information can be found [here](https://github.com/apollographql/apollo-kotlin/tree/main/intellij-plugin).
179
-
180
-
## Releases
181
-
182
-
The latest version is [](https://repo1.maven.org/maven2/com/apollographql/apollo/)
183
-
184
-
Check the [changelog](https://github.com/apollographql/apollo-kotlin/releases) for the release history.
185
-
186
-
Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollographql/apollo/). The plugin is additionally hosted on the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.apollographql.apollo)
187
-
188
-
```kotlin
189
-
plugins {
190
-
id("com.apollographql.apollo") version "4.0.0-rc.1"
| What do you like best about Apollo Kotlin? What needs to be improved? Please tell us by taking a [one-minute survey](https://docs.google.com/forms/d/e/1FAIpQLSczNDXfJne3ZUOXjk9Ursm9JYvhTh1_nFTDfdq3XBAFWCzplQ/viewform?usp=pp_url&entry.1170701325=Apollo+Kotlin&entry.204965213=Readme). Your responses will help us understand Apollo Kotlin usage and allow us to serve you better. |
242
22
243
-
Apollo Kotlin is very modular and publishes several artifacts.
23
+
## 🚀 Apollo Kotlin
244
24
245
-
* Artifacts ending with `-incubating` are not finalized yet and subject to change any time.
246
-
* Other artifacts observe [Semantic Versioning](https://semver.org/).
247
-
* No breaking change should be introduced in minor or patch releases except for symbols annotated with `@ApolloExperimental` that are subject to change at any time.
248
-
* Deprecated symbols may be removed in the next major release. We strongly recommend removing deprecated usages before migrating to the next major version.
25
+
Apollo Kotlin is a strongly typed GraphQL client that generates Kotlin models for your GraphQL operations.
249
26
250
-
## Contributing
27
+
Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.
251
28
252
-
If you'd like to contribute, please see [Contributing.md](https://github.com/apollographql/apollo-kotlin/blob/main/CONTRIBUTING.md).
29
+
Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
253
30
254
-
## Community integrations
31
+
This library is designed with Android in mind, but you can use it in any Kotlin application, including multiplatform.
255
32
256
-
* If you're using the [Maven](https://maven.apache.org/) build tool, [apollo-client-maven-plugin](https://github.com/aoudiamoncef/apollo-client-maven-plugin) is a Maven plugin that calls the Apollo Kotlin compiler to generate your Java/Kotlin sources.
257
-
* If you're using [Absinthe Phoenix subscriptions](https://hexdocs.pm/absinthe_phoenix/readme.html), [kotlin-phoenix](https://github.com/ajacquierbret/kotlin-phoenix) has a [PhoenixNetworkTransport](https://github.com/ajacquierbret/kotlin-phoenix/blob/main/kotlinphoenix-adapters/src/commonMain/kotlin/io/github/ajacquierbret/kotlinphoenix/adapters/apollo/PhoenixNetworkTransport.kt) that you can use together with `ApolloClient` ([doc](https://github.com/ajacquierbret/kotlin-phoenix/tree/main/kotlinphoenix-adapters))
33
+
## 📚 Documentation
258
34
259
-
## Additional resources
35
+
All Apollo Kotlin documentation, including caching and helpful recipes, can be found at: <br/>
-[Confetti](https://github.com/joreilly/Confetti): A Kotlin Multiplatform conference app using Apollo Kotlin, SwiftUI and Jetpack Compose.
262
-
-[MortyComposeKMM](https://github.com/joreilly/MortyComposeKMM): A Kotlin Multiplatform Github template using Apollo Kotlin, SwiftUI and Jetpack Compose.
263
-
-[A journey to Kotlin multiplatform](https://www.youtube.com/watch?v=GN6LHrqyimI): how the project was moved to Kotlin multiplatform, talk given at Kotliners in June 2020.
264
-
-[#125, Fragmented Podcast](http://fragmentedpodcast.com/episodes/125/): Why's and How's about Apollo Kotlin and the entire journey.
265
-
-[GraphQL.org](http://graphql.org) for an introduction and reference to GraphQL itself.
266
-
-[apollographql.com](http://www.apollographql.com/) to learn about Apollo open-source and commercial tools.
267
-
-[The Apollo blog](https://www.apollographql.com/blog/) for long-form articles about GraphQL, feature announcements for Apollo, and guest articles from the community.
268
-
-[The Apollo Twitter account](https://twitter.com/apollographql) for in-the-moment news.
38
+
The Apollo Kotlin API reference can be found at: <br/>
[Apollo](https://apollographql.com/) builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:
273
44
@@ -276,6 +47,6 @@ If you'd like to contribute, please see [Contributing.md](https://github.com/apo
276
47
*[Apollo Client](https://www.apollographql.com/apollo-client/) – The most popular GraphQL client for the web. Apollo also builds and maintains [Apollo iOS](https://github.com/apollographql/apollo-ios) and [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin).
277
48
*[Apollo Server](https://www.apollographql.com/docs/apollo-server/) – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.
278
49
279
-
## Learn how to build with Apollo
50
+
## 🎓 Learn how to build with Apollo
280
51
281
52
Check out the [Odyssey](https://odyssey.apollographql.com/) learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the [Apollo Community](https://community.apollographql.com/) to interact with and get technical help from the GraphQL community.
0 commit comments