docs improvments

README.md

@@ -73,6 +73,7 @@ All methods return promises. Examples requests and responses are available for a
 - Misc
   - [`getCapabilities()`](./examples/getCapabilities.md)
   - [`getMapData`](./examples/getMapData.md)
+  - [Using the Development Server](./examples/dev-server.md)
 - Authentication (browser only, not available in NodeJS)
   - `login`
   - `logout`
@@ -171,3 +172,13 @@ OSM.configure({ basicAuth: { username: "...", password: "..." } });
 // Example:
 await OSM.createChangesetComment(114733070, "Thanks for your edit!");
 ```
+
+## Comparison with osm-request
+
+This library offers several advantages over [osm-request](https://github.com/osmlab/osm-request):
+
+1. **TypeScript support**: osm-api-js is built with TypeScript, providing better type safety and developer experience.
+2. **Simpler API**: The API is designed to be more straightforward and easier to use.
+3. **Smaller bundle size**: With fewer dependencies, osm-api-js has a noticeably smaller bundle size.
+
+While osm-request has been revived, osm-api-js was created when osm-request was abandoned and lacked OAuth 2 support.

examples/dev-server.md

@@ -0,0 +1,14 @@
+# Using the Development Server
+
+For experimenting with the API, use the development server documented [here](https://osm.wiki/API_v0.6#URL_+_authentication).
+It uses a separate database with less data, allowing you to test without affecting the real database.
+
+1. Create an account and application key on the [development server](https://master.apis.dev.openstreetmap.org/oauth2/applications).
+
+2. Configure the library to use the development server:
+
+```ts
+OSM.configure({ apiUrl: "https://master.apis.dev.openstreetmap.org" });
+```
+
+Now you're ready to start making requests to the development server!

examples/uploadChangeset.md

@@ -27,3 +27,50 @@ Response:
 ```
 
 (changeset number)
+
+## Detailed Examples
+
+### Updating existing features
+
+```ts
+import { getFeature } from "osm-api";
+
+const [feature] = await getFeature("node", 12345);
+
+feature.tags ||= {};
+feature.tags.amenity = "restaurant";
+
+await uploadChangeset(
+  { created_by: "MyApp 1.0", comment: "tagging as resturant" },
+  { create: [], modify: [feature], delete: [] }
+);
+```
+
+### Creating new features
+
+To create a new node, several of the fields will have be be blanked out
+
+```ts
+import { OsmNode } from "osm-api";
+
+const newNode: OsmNode = {
+  type: "node",
+  lat: 123.456,
+  lon: 789.123,
+  tags: {
+    amenity: "restaurant",
+  },
+  id: -1, // Negative ID for new features
+
+  changeset: -1,
+  timestamp: "",
+  uid: -1,
+  user: "",
+  version: 0,
+};
+
+await uploadChangeset(
+  { created_by: "MyApp 1.0", comment: "tagging as resturant" },
+  { create: [newNode], modify: [], delete: [] }
+);
+```