feat: set v2 as default API version; add observation search request parameter descriptions; default ignore_photos to true on observation update

Author: pleary

lib/inaturalist_api.js

@@ -247,12 +247,12 @@ InaturalistAPI.server = async ( ) => {
     dfault( "get", "/v1/computervision/language_search", ComputervisionController.languageSearch );
   }
 
-  app.get( "/", routesV1.docs );
-  app.get( "/docs", routesV1.docs );
+  app.get( "/", routesV1.v2_docs_redirect );
+  app.get( "/docs", routesV1.v2_docs_redirect );
   app.get( "/swagger.json", routesV1.swaggerRedirect );
   app.get( "/robots.txt", routesV1.robots );
 
-  app.get( "/v1", routesV1.docs );
+  app.get( "/v1", routesV1.v1_docs_redirect );
   app.get( "/v1/swagger.json", routesV1.swaggerJSON );
   app.get( "/v1/ping", ( req, res ) => {
     res.setHeader( "Cache-Control",

lib/routes_v1.js

@@ -31,7 +31,11 @@ routesV1.defaultAsync = async ( method, req, res ) => {
   }
 };
 
-routesV1.docs = ( req, res ) => {
+routesV1.v2_docs_redirect = ( req, res ) => {
+  res.redirect( "/v2/docs" );
+};
+
+routesV1.v1_docs_redirect = ( req, res ) => {
   res.redirect( "/v1/docs" );
 };
 
@@ -54,7 +58,7 @@ routesV1.swaggerJSON = ( req, res ) => {
 
 routesV1.robots = ( req, res ) => {
   res.type( "text/plain" );
-  res.send( "User-agent: *\nAllow: /v1/docs\nDisallow: /" );
+  res.send( "User-agent: *\nAllow: /v1/docs\nAllow: /v2/docs\nDisallow: /" );
 };
 
 module.exports = routesV1;

openapi/doc.js

@@ -29,6 +29,7 @@ fs.readdirSync( "./openapi/schema/request" ).forEach( file => {
 
 const parsedUrl = nodeUrl.parse( config.currentVersionURL );
 const url = `${parsedUrl.protocol}//${parsedUrl.host}/v2`;
+const schemaUrl = `${parsedUrl.protocol}//${parsedUrl.host}/v2/api-docs`;
 const risonUrl = `${url}/observations?fields=(species_guess:!t,user:(login:!t))`;
 
 const apiDoc = {
@@ -37,10 +38,10 @@ const apiDoc = {
     url
   }],
   info: {
-    title: "Test iNaturalist Version 2 API",
-    version: "2.0.0-alpha",
+    title: "iNaturalist Version 2 API",
+    version: "2.2.0",
     description: `## ${url}
-**UNDER ACTIVE DEVELOPMENT, USE OF THIS ALPHA RELEASE NOT RECOMMENDED**
+The OpenAPI 3.0 schema definition of this API is available at <${schemaUrl}>.
 
 These API methods return data in JSON/JSONP and PNG response formats. Visit our
 [developers page](https://www.inaturalist.org/pages/developers) for more
@@ -96,7 +97,7 @@ a URL-friendly variant of JSON. If you want to request fields like
 
 you can encode those fields as RISON:
 
-<a href="${risonUrl}">${risonUrl}</a>
+<${risonUrl}>
 
 This is our preferred way to specify fields because it maintains the caching
 benefits of URLs that are unique to their responses, and it avoids the

openapi/schema/request/observations_search.js

@@ -2,7 +2,9 @@ const Joi = require( "joi" );
 
 module.exports = Joi.object( ).keys( {
   fields: Joi.any( ),
-  ignore_photos: Joi.boolean( ),
+  ignore_photos: Joi.boolean( )
+    .default( true )
+    .description( "**NOTE: if `ignore_photos` is set to false, all photos will be removed from the observation**" ),
   observation: Joi.object( ).keys( {
     uuid: Joi.string( ).guid( { version: "uuidv4" } ),
     captive_flag: Joi.boolean( ),

openapi/schema/request/observations_update.js

@@ -3,16 +3,16 @@ const request = require( "supertest" );
 
 describe( "routes", ( ) => {
   describe( "index", ( ) => {
-    it( "redirects to /v1/docs", function ( done ) {
+    it( "redirects to /v2/docs", function ( done ) {
       request( this.app ).get( "/" )
-        .expect( "Location", "/v1/docs", done );
+        .expect( "Location", "/v2/docs", done );
     } );
   } );
 
   describe( "docs", ( ) => {
-    it( "redirects to /v1/docs", function ( done ) {
+    it( "redirects to /v2/docs", function ( done ) {
       request( this.app ).get( "/docs" )
-        .expect( "Location", "/v1/docs", done );
+        .expect( "Location", "/v2/docs", done );
     } );
   } );
 
@@ -39,7 +39,7 @@ describe( "routes", ( ) => {
     it( "renders a robots.txt file", function ( done ) {
       request( this.app ).get( "/robots.txt" )
         .expect( res => {
-          expect( res.text ).to.eq( "User-agent: *\nAllow: /v1/docs\nDisallow: /" );
+          expect( res.text ).to.eq( "User-agent: *\nAllow: /v1/docs\nAllow: /v2/docs\nDisallow: /" );
         } ).expect( "Content-Type", /plain/ )
         .expect( 200, done );
     } );

test/integration/v1/basic.js

@@ -857,7 +857,7 @@ describe( "Observations", ( ) => {
       // controller will load fresh data from the ES index, so if we want to see
       // a change without actually changing data, we need to stub the v1
       // controller reponse
-      sinon.stub( ObservationsController, "update" )
+      const stub = sinon.stub( ObservationsController, "update" )
         .callsFake(
           ( ) => ( { ...fixtureObs, description: newDesc } )
         );
@@ -869,10 +869,34 @@ describe( "Observations", ( ) => {
         .expect( res => {
           expect( res.body.results[0].uuid ).to.eq( fixtureObs.uuid );
           expect( res.body.results[0].description ).to.eq( newDesc );
+          stub.restore( );
         } )
         .expect( "Content-Type", /json/ )
         .expect( 200, done );
     } );
+
+    it( "defaults ignore_photos to true", function ( done ) {
+      nock( "http://localhost:3000" )
+        .put( `/observations/${fixtureObs.uuid}`, JSON.stringify( { ignore_photos: true } ) )
+        .reply( 200, [{ id: fixtureObs.id, uuid: fixtureObs.uuid }] );
+      request( this.app ).put( `/v2/observations/${fixtureObs.uuid}` )
+        .set( "Authorization", token )
+        .set( "Content-Type", "application/json" )
+        .expect( 200, done );
+    } );
+
+    it( "can set ignore_photos to false", function ( done ) {
+      nock( "http://localhost:3000" )
+        .put( `/observations/${fixtureObs.uuid}`, JSON.stringify( { ignore_photos: false } ) )
+        .reply( 200, [{ id: fixtureObs.id, uuid: fixtureObs.uuid }] );
+      request( this.app ).put( `/v2/observations/${fixtureObs.uuid}` )
+        .send( {
+          ignore_photos: false
+        } )
+        .set( "Authorization", token )
+        .set( "Content-Type", "application/json" )
+        .expect( 200, done );
+    } );
   } );
 
   describe( "delete", ( ) => {